Home | About | Sematext search-lucene.com search-hadoop.com
 Search Hadoop and all its subprojects:

Switch to Threaded View
Accumulo, mail # dev - Review Request 15857: ACCUMULO-1931 - Javadoc for core.data


Copy link to this message
-
Re: Review Request 15857: ACCUMULO-1931 - Javadoc for core.data
Christopher Tubbs 2013-12-06, 22:05


> On Dec. 6, 2013, 2:26 p.m., Sean Busbey wrote:
> > core/src/main/java/org/apache/accumulo/core/data/doc-files/mutation-serialization.html, line 3
> > <https://reviews.apache.org/r/15857/diff/4/?file=393530#file393530line3>
> >
> >     Just to verify, this html file will get included in the generated javadocs?
> >    
> >     Reading the javadoc plugin[1], it looks like maybe it needs to be in core/src/main/javadoc/org/apache/accumulo/core/data/doc-files/mutation-serialization.html
> >    
> >     [1]: http://maven.apache.org/plugins/maven-javadoc-plugin/examples/javadoc-resources.html
> >
>
> Bill Havanki wrote:
>     It is. I'm using a capability of the javadoc tool itself[1] rather than the plugin. Interesting that there are multiple options for this.
>    
>     [1]: http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#unprocessed
>
> Sean Busbey wrote:
>     I saw that the javadoc tool will work with this location, just not sure if the javadoc Maven plugin changes the behavior. Might be worth moving it to src/main/javadoc to keep things more in line with "the Maven way."
>
> Bill Havanki wrote:
>     (Adding comment that I had sent in email, sorry for the repetition)
>    
>     It still works even under the Maven plugin, i.e., I checked by running mvn javadoc:javadoc and the file was transferred. So, leaving it where it is lets it work both with and without Maven.
>
> Christopher Tubbs wrote:
>     Why not use package-info.java, for package-level javadocs?
>
> Sean Busbey wrote:
>     This particular file just provides an explanation of the Mutation serialization formats, it's not really package-level information. AFAICT, the only reason it's not going on the Mutation class directly is that there's too much to cover.

If it's too much to warrant inclusion on the Mutation class, and isn't appropriate at the package-level, then it seems to me that it should go in the user documentation, and shouldn't be part of the javadocs at all.
- Christopher
-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/15857/#review29897
-----------------------------------------------------------
On Dec. 6, 2013, 2:56 p.m., Bill Havanki wrote:
>
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/15857/
> -----------------------------------------------------------
>
> (Updated Dec. 6, 2013, 2:56 p.m.)
>
>
> Review request for accumulo.
>
>
> Bugs: ACCUMULO-1931
>     https://issues.apache.org/jira/browse/ACCUMULO-1931
>
>
> Repository: accumulo
>
>
> Description
> -------
>
> Javadoc additions and updates to classes in org.apache.accumulo.core.data.
>
>
> Diffs
> -----
>
>   core/src/main/java/org/apache/accumulo/core/data/ArrayByteSequence.java eaa61b9950b691ed5955af3178a3aa939291e8bf
>   core/src/main/java/org/apache/accumulo/core/data/ByteSequence.java 4dc921c5efc44d374032c623f50e4218aa6c7299
>   core/src/main/java/org/apache/accumulo/core/data/Column.java a56c01d6604a30153739ed1329d034e3932f2e2f
>   core/src/main/java/org/apache/accumulo/core/data/ColumnUpdate.java 641ca3a740ed384ab93f4b2d3c08c928daadfb2f
>   core/src/main/java/org/apache/accumulo/core/data/ComparableBytes.java ce61844375617c36ede5e0e411b439205329b023
>   core/src/main/java/org/apache/accumulo/core/data/Condition.java fc8f2bf0394ae658bacfa94804b4b81f19a0c0c2
>   core/src/main/java/org/apache/accumulo/core/data/ConstraintViolationSummary.java 2929bc610df9352374621d29caea7732bd50847d
>   core/src/main/java/org/apache/accumulo/core/data/Key.java de9e22d9ebff5442633dc578613fd7d033afc9c5
>   core/src/main/java/org/apache/accumulo/core/data/KeyValue.java cc48322f9785ad508cc7925279f5e559629f3721
>   core/src/main/java/org/apache/accumulo/core/data/Mutation.java 5e281f2bfef7e164c9f0e0c9a7132e94012d7186
>   core/src/main/java/org/apache/accumulo/core/data/PartialKey.java 2049881fe26b5f237db39a412a88e2e2017f5cc9