accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Bill Havanki" <bhava...@clouderagovt.com>
Subject Re: Review Request 15857: ACCUMULO-1931 - Javadoc for core.data
Date Mon, 09 Dec 2013 14:06:22 GMT


> 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.
> 
> 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.
> 
> Sean Busbey wrote:
>     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.

Explaining my thinking: I created the separate doc because I did think it was too much for
the Mutation class itself, as many people won't care about it. Also, since it only pertains
to Mutation, putting it in the package overview seemed inappropriate.

Personally, I'm fine with wherever the proper eventual home for this should be. I know that
we are thinking about consolidating docs (ACCUMULO-1490, for example). Creating this as a
Javadoc at least has the current benefit of not introducing a new doc source. I wrote the
doc in very plain HTML, knowing that it would most likely need to be moved and enhanced to
some future permanent location. Sean's concern about "those on isolated networks" resonates
with me as well.


- Bill


-----------------------------------------------------------
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

>   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