Javadoc contributions

[Bill Havanki <bh...@clouderagovt.com>]

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

Re: Javadoc contributions

[Bill Havanki <bh...@clouderagovt.com>]

Thanks Christopher, for your well-thought-out advice.

I have been generating javadoc for anything with visibility public or
protected, and so I think that extends beyond the "public API" (I forget
its definition). I believe documentation of even internal methods is useful
for someone like me who is learning the system, and for the integrator who
occasionally has to dive in to figure something out.

I generally don't include details in javadoc, but leave it at a
specification / black-box level - put in this, get this out; these facets
of the environment matter; these are error conditions, assumptions, etc.
That way they are tolerant of implementation "drift" as you put it. I don't
have much interest in authoring detailed explanations of the implementation
for inclusion as (package-level, say) javadoc; I feel they are better
presented as blog entries / presentations / wiki pages.

I definitely want to also contribute unit tests to improve coverage, but
that would be a separate effort, at least for just me.

Bill


On Mon, Nov 25, 2013 at 4:12 PM, Christopher <ct...@apache.org> wrote:

> 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 <bh...@clouderagovt.com>
> 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
> > | - - -
>



-- 
| - - -
| Bill Havanki
| Solutions Architect, Cloudera Government Solutions
| - - -

Re: Javadoc contributions

[Christopher <ct...@apache.org>]

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 <bh...@clouderagovt.com> 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
> | - - -