accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Sean Busbey" <s...@manvsbeard.com>
Subject Re: Review Request 15857: ACCUMULO-1931 - Javadoc for core.data
Date Fri, 06 Dec 2013 22:25:24 GMT


> On Dec. 6, 2013, 7: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.
> 
> Christopher Tubbs wrote:
>     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.

Are details of our internal serialization formats for the Mutation class appropriate for user
facing documentation?

This seemed like a good fit for things people can use trying to develop within the Accumulo
codebase. Reading the page, it's definitely more than I would normally put on the class, but
definitely not something I would expose to users.

Do we use our Apache wiki space for developer docs yet? This is the sort of thing I'd expect
to find there on other projects. The disadvantage of putting it there and linking is that
those on isolated networks wouldn't be able to follow the link as they could in this case.


- Sean


-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/15857/#review29897
-----------------------------------------------------------


On Dec. 6, 2013, 7: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, 7: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

>   core/src/main/java/org/apache/accumulo/core/data/Range.java 70857348cefd0941e5ffcf6e5d569f09870101e4

>   core/src/main/java/org/apache/accumulo/core/data/Value.java 7d3cf8f20aa12205d25027d6ad06e4a3f6062b2e

>   core/src/main/java/org/apache/accumulo/core/data/doc-files/mutation-serialization.html
PRE-CREATION 
>   core/src/main/java/org/apache/accumulo/core/util/UnsynchronizedBuffer.java b640581bebbb87f1ac9a36f71275fa5dc8ef1223

> 
> Diff: https://reviews.apache.org/r/15857/diff/
> 
> 
> Testing
> -------
> 
> Compiled successfully; mvn javadoc:javadoc ran with no errors from the javadoc in this
patch.
> 
> 
> Thanks,
> 
> Bill Havanki
> 
>


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message