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