Improve javadoc generation

Description

The javadoc generation could be improved a bit:

  • We should exclude all org/geotools/resources/** packages from javadoc.
    They are for internal purpose only and should not be visible to users.

  • Max memory could be increased from 128M to 384M. Geotools's javadoc
    is becoming quite big, and too few memory slow it down.

  • A @todo tag could be added in addition of @task, as an anticipation
    of a possible future standard tag. Sun is considerating using @todo
    as a standard tag. Furthermore, @todo are automatically recognized
    by some IDE like Netbeans.

  • A time stamp would be usefull. In an Ant task, it could be written
    as below:

<tstamp>
<format property="TODAY" pattern="yyyy-MM-dd" locale="ca"/>
</tstamp>

<javadoc header = "Geotools<br>Build $
{TODAY}
"
... etc ...>
</javadoc>

Environment

None

Activity

Show:
codehaus
April 10, 2015, 2:58 PM

CodeHaus Comment From: dzwiers - Time: Thu, 24 Feb 2005 18:21:22 -0600
---------------------
Two comments:

1) lets ot start deciding what to generate javadoc comments for in jira ... sounds like a meeting item Martin. (btw, my vote is -1)

2) Adding non-standardized tags has created issues for me in the past, so I also vote against that until they are standard in the codebase's language (Java 1.4.2).

codehaus
April 10, 2015, 2:58 PM

CodeHaus Comment From: desruisseaux - Time: Thu, 24 Feb 2005 18:50:46 -0600
---------------------
The exclusion of org/geotools/resources/** packages was already decided in IRC meeting about 2 years ago, before Refraction Research joins Geotools development. 'resources' has never been intented to be a visible package. This proposal is just about applying a decision that already been voted.

The @task tag has been decided in an IRC meeting too, again before Refraction Research join the Geotools project. It was James's proposal (not mine), but I agree that we needed something like that. Now that Sun seems to be going toward a standard @todo tag, I'm suggesting to anticipate the move.

Of course we can revisit those past decisions. I will refactor my @task and @todo tags toward whatever decision is taken (I admit that I mix both of them currently).

codehaus
April 10, 2015, 2:58 PM

CodeHaus Comment From: desruisseaux - Time: Thu, 24 Feb 2005 18:52:04 -0600
---------------------
In addition, if the javadoc is generated using J2SE 1.5 "javadoc" tool, the following command-line option could be added:

    -keywords

It will generates some meta-information that help to find methods or classes by their name using Google for example.

codehaus
April 10, 2015, 2:58 PM

CodeHaus Comment From: desruisseaux - Time: Fri, 24 Nov 2006 16:30:35 -0600
---------------------
We switched to maven-javadoc-plugin since Geotools 2.3. Our plugin configuration is similar to some of the item described in this task.

Assignee

Unassigned

Reporter

codehaus

Triage

None

Components

Fix versions

Affects versions

Priority

Lowest
Configure