I'd say... it depends on what you're documenting and how you're documenting it. Tests for correct behavior, with comments about the expectations, are often better than javadocs for internal, implementing, code and a single ticket for a single set of related tests/documented expectations seems appropriate. For public API, most things are already documented, so specific tickets could be opened for anything overlooked in that area, as needed.
Package and class-level javadocs that explain internal details about how things work may be useful under a single ticket, if they are explaining the same overall behavior/architecture, and separate tickets otherwise (eg. explaining garbage collector implementation, vs. monitor logging implementation). But, these should probably not going into too much detail about the specific implementation, or they will lose relevancy as implementation drifts. In summary: 1) Class, package, and method-level documentation is welcome for all things in the public API. (tickets as needed to address anything overlooked... or supplement existing feature ticket with an additional commit for javadocs, if a new feature is added and forgets documentation). 2) Class and package-level documentation is welcome for internal implementations, if it helps explain the expected behavior without going into internal details, which drift and change. (separate tickets for unrelated architectures/overviews) 3) Keep the comments as local as possible, to avoid drift. 4) For implementing code, it's probably better to write explicit unit tests, with comments, to test the expected behavior, rather than add comments to the internal methods themselves, which add bloat and could become misleading and incorrect over time. (separate tickets for separate sets of related tests) -- Christopher L Tubbs II http://gravatar.com/ctubbsii On Mon, Nov 25, 2013 at 3:45 PM, Bill Havanki <[email protected]> wrote: > In an effort to learn the Accumulo code, I've been working through it and > writing Javadoc along the way. I'd like to start contributing it to the > project. Is the best way to do that simply to create new JIRA tickets > covering the contributions? I have a lot so far, but I would only submit > digestible portions at a time, so as not to overwhelm anyone. > > Thanks for your advice, > Bill > > -- > | - - - > | Bill Havanki > | Solutions Architect, Cloudera Government Solutions > | - - -
