Mailing-List: contact dev-help@accumulo.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@accumulo.apache.org
MIME-Version: 1.0
In-Reply-To: 
 <CADczPYQyEeapzhcsgRCo=2ZbHAKJ12fTZWgxbziE81RF0LUuVw@mail.gmail.com>
References: 
 <CAL5zq9YAOdSXABok0RH5Q5h+wgJ=p9t2-7Oct+DJoSeCXsRFBA@mail.gmail.com>
	<CADczPYQyEeapzhcsgRCo=2ZbHAKJ12fTZWgxbziE81RF0LUuVw@mail.gmail.com>
Date: Wed, 30 Jan 2013 20:17:43 -0500
Message-ID: 
 <CAL5zq9bqUJhjTPU2EXEzPZGg8Rd=rX9xyrken+Y2VXNpOSN0BQ@mail.gmail.com>
Subject: Re: Thoughts on useless/malformed javadoc comments
From: Christopher <ctubbsii@apache.org>
To: dev@accumulo.apache.org, vines@apache.org
Content-Type: multipart/alternative; boundary=bcaec554d84ad3540904d48b64cd

--bcaec554d84ad3540904d48b64cd
Content-Type: text/plain; charset=ISO-8859-1

I'm not sure what you mean by "enforce", but it's a simple matter to tell
Eclipse to produce a warning on malformed javadocs (which includes @param
tags that don't match actual parameters), and I believe there's also an
option to add and/or warn about missing @param tags, as well as a bunch of
other options. We could probably add some flags to the maven-javadoc-plugin
to throw errors in the build for malformed javadocs (I'll look into that).

The main thing, though, is that the javadoc tool is smart enough to derive
most of the javadoc from the method signature... without the comment. So,
unless some value is actually added to the javadoc comment, it doesn't
matter if it's in sync with the method or not, it's still not useful, as
its only effective function is to bulk up the size of the source file.


--
Christopher L Tubbs II
http://gravatar.com/ctubbsii


On Wed, Jan 30, 2013 at 8:10 PM, John Vines <vines@apache.org> wrote:

> One of the things I notice while doing a large amount of refactoring was
> the pain of having to be careful about updating javadoc comments. Is it
> possible to enforce comments corresponding to actual method calls? It's not
> perfect but our would help.
>
> Sent from my phone, please pardon the typos and brevity.
> On Jan 30, 2013 7:56 PM, "Christopher" <ctubbsii@apache.org> wrote:
>
> > (For the record, when I say "useless", I mean javadoc comments that
> consist
> > solely of the auto-generated skeleton, derived from the method signature,
> > with little or nothing added)
> >
> > In our code template, we add javadoc tags to new methods, classes, etc. I
> > think this is a good idea... except that this also tends to generate a
> lot
> > of "malformed javadoc" warnings if you check for those in your
> environment
> > (I do, because I dislike javadocs that break and/or become useless).
> >
> > I'm wondering if it's better to remove this from the code template, so
> > javadocs that get automatically generated, but then immediately
> > and subsequently ignored (worse when the javadoc references a param from
> a
> > previous version of the method that no longer exists or was renamed),
> don't
> > keep appearing throughout the code.
> >
> > The risks associated with removing these from the code template is that
> > javadocs won't be added to the public API, unless we prioritize the act
> of
> > consciously and thoughtfully adding them.
> >
> > The risks of not removing it is that we have a bunch of useless and/or
> > malformed javadocs, or even just out-of-date javadocs that no longer
> > reflect the method signature or functionality, that stick around just
> > because it's part of the code template, but not because we consciously
> > wanted one, and  remain that way because it isn't a priority to fix them.
> > Perhaps this is just a personal pet peeve that I should get over, but I
> > feel like this isn't the best option.
> >
> > Of course, we could internally discourage the use of javadoc comments
> that
> > don't serve a function or are malformed, and encourage deliberately
> keeping
> > them up-to-date in the public API.
> >
> > Anybody have any thoughts on this?
> >
> > --
> > Christopher L Tubbs II
> > http://gravatar.com/ctubbsii
> >
>

--bcaec554d84ad3540904d48b64cd--