On Mon, Mar 30, 2015 at 3:06 AM, Michael T. Pope <mp...@computer.org> wrote:
> On Mon, 30 Mar 2015 01:13:32 -0500
> Caleb Williams <cale...@gmail.com> wrote:
> > Plus it didn't help that I misinterpreted Michael's comment on the
> > merge request.
>
> I should probably clarify here (rather than on the merge request) some
> JavaDoc practices used in FreeCol. Obviously there are two consumers of
> JavaDoc: humans reading the code, and JavaDoc-manipulating programs. The
> former is more important IMHO:-), but the latter can not be ignored.
>
I understand that better now. Thanks. The issue is that I cannot access the
Merge Request discussion in any way once it's been submitted. After that,
email is the only recourse.
>
> - There has been little consistency about when JavaDoc is added. It is ok
> to add new code without it, especially for small obvious routines. I
> personally prefer to err on the side of more doco rather than less, but
> I have never seen a contribution bounced due to its documentation or
> lack thereof.
>
> - Functions that inherit documentation just get {@inheritDoc} and nothing
> more. Anything else is clutter. Of course, @Override etc is ok though.
>
That is the bulk of what I'm adding, which as I understand it hurts
nothing, but *can* help the compiler do its job. Fortunately, it looks like
I'll be duplicating some work so we'll see how long that takes, and if I
can get the issues I described in the previous email licked so that I'm not
resubmitting changes that include previous changes.
>
> - Running "ant javadoc" every so often, and cleaning up the inevitable
> slips is a good idea.
>
I'll have to look more at that when I'm done doing this semi-automated code
clean to see what the results are.
Best,
--
*Caleb R. Williams*
------------------------------------------------------------------------------
Dive into the World of Parallel Programming The Go Parallel Website, sponsored
by Intel and developed in partnership with Slashdot Media, is your hub for all
things parallel software development, from weekly thought leadership blogs to
news, videos, case studies, tutorials and more. Take a look and join the
conversation now. http://goparallel.sourceforge.net/
_______________________________________________
Freecol-developers mailing list
Freecol-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/freecol-developers
