The developers guide is open to a change procedure; if we want to make that a
minimum standard. Indeed since the developers guide needs a bit of love;
perhaps we could ask for a stay of execution; and just do quick votes on the
email list here?
Personally my bare minimum is a single sentence class javadoc. And yes I agree
for anything that is considered api (such as gt-opengis or gt-api module that
we should expect a lot more :-D ).
Looks like you are done your hacking on the @source tag fixer; did the work go
well? Do you want to run it on gt-opengis and gt-api for me tomorrow?
--
Jody Garnett
On Tuesday, 24 May 2011 at 12:30 AM, Michael Bedward wrote:
> Thanks Jody. Although there are no javadoc minimum standards I wonder
> if it would be ok to add some encouragement for people to have
> javadocs for at least the most important public methods in a class. It
> makes such a difference :)
>
> I've updated the page for the new InsertSourceTag usage.
>
> Michael
>
> On 23 May 2011 19:55, Jody Garnett <[email protected]> wrote:
> > Based on the conversation from about the @source tag; I have added some
> > javadocs recommendations to the developers guide.
> > http://docs.geotools.org/latest/developer/guide/conventions/code/style.html
> > (And stolen a live code example from SimpleFeatureType which seems to
> > illustrate all the points).
> >
> > Can I ask for a review of the following; any pet javadocs peeves feel free
> > to add to that page.
> >
> > Javadocs
> >
> > The project does not have any minimum standards for javadocs; so it is not
> > something that will cause you to fail a code review.
> >
> > Here is an example javadoc to use as a reference for the following
> > conversation:
> >
> > /**
> > * An instance of {@link SimpleFeatureType} composed of fixed list values in
> > a known order.
> > * <p>
> > * The definition of a "simple feature" can be summed up as the following:
> > * <ul>
> > * <li>made up of only non-complex attributes, no associations
> > * <li>attributes are of multiplicity 1
> > * <li>attributes are ordered
> > * <li>attribute names are unqualified (namespaceURI == null)
> > * </ul>
> > * </p>
> > * <p>
> > * <h3>Attribute Access</h3>
> > * The order and multiplicity restrictions on simple feature make attribute
> > * values accessible via an index. For example consider the following
> > shapefile
> > * entry:
> > * <pre>
> > * | GEOMETRY | INT | STRING |
> > * | POINT(0 0) | 0 | "zero" |
> > * </pre>
> > * Accessing attributes via index would look like:
> > * <pre>
> > * SimpleFeature feature = ...;
> > *
> > * Geometry g = (Geometry) feature.getAttribute( 0 );
> > * Integer i = (Integer) feature.getAttribute( 1 );
> > * String s = (String) feature.getAttribute( 2 );
> > * </pre>
> > * One could also access by name:
> > * <pre>
> > * SimpleFeature feature = ...;
> > *
> > * Geometry g = (Geometry) feature.getAttribute( "GEOMETRY" );
> > * Integer i = (Integer) feature.getAttribute( "INT" );
> > * String s = (String) feature.getAttribute( "STRING" );
> > * </pre>
> > * </p>
> > * <p>
> > * <b>Note:</b> Attribute access via getAttribute() methods returns
> > attribute
> > * values, and not the attributes themselves. For access to the actual
> > attributes
> > * {@link ComplexAttribute#getProperty(String)} can be used.
> > * </p>
> > *
> > * @see SimpleFeatureType
> > *
> > * @author Jody Garnett (LISAsoft)
> > * @author Justin Deoliveira (The Open Planning Project)
> > * @since 2.5
> > * @version 8.0
> > * @source
> > $URL:http://svn.osgeo.org/geotools/trunk/modules/library/opengis/src/main/java/org/opengis/feature/simple/SimpleFeature.java
> > $
> > */
> >
> > We do encourage developers to:
> >
> > Have “topic sentence” for each class (to help IDE developers understand what
> > the class is). (This is a reminder of normal javadoc convention).
> >
> > Use <pre> for any code examples (This is a reminder of normal javadoc
> > convention).
> >
> > Use @author tags to credit individuals involved, you can credit their
> > organisation in brackets
> >
> > Use @since to list the version number in which the interface first appeared
> >
> > Update @version annotation if the interface is ever modified
> >
> > We have a custom @source annotation to help our javadocs look pretty (and
> > reference the appropraite module).
> >
> > The taglet code discards $URL: $ if you would like to use svn to expand the
> > correct path as needed.
> >
> > There is a tool you can use to fill in the @src annotation.
> >
> > To insert missing source tag in all source files for module gt-wps.:
> >
> > cd trunk/build/maven/javadoc
> > mvn exec:java -Dexec.mainClass=org.geotools.maven.tools.InsertSourceTag
> > -DcommandlineArgs=../../modules/unsupported/wps/src
> >
> > If you are using svn expansion you can set the svn:keyword expansion up:
> >
> > find ../modules/unsupported/wps/src -type f -name '*.java' -exec svn ps
> > svn:keywords "Id URL" {} \;
> >
> > If you would like to include any diagrams or pictures please add them to
> > a doc-files folder. (This is a reminder of normal javadoc convention).
> >
> > ------------------------------------------------------------------------------
> > What Every C/C++ and Fortran developer Should Know!
> > Read this article and learn how Intel has extended the reach of its
> > next-generation tools to help Windows* and Linux* C/C++ and Fortran
> > developers boost performance applications - including clusters.
> > http://p.sf.net/sfu/intel-dev2devmay
> > _______________________________________________
> > Geotools-devel mailing list
> > [email protected]
> > https://lists.sourceforge.net/lists/listinfo/geotools-devel
>
------------------------------------------------------------------------------
What Every C/C++ and Fortran developer Should Know!
Read this article and learn how Intel has extended the reach of its
next-generation tools to help Windows* and Linux* C/C++ and Fortran
developers boost performance applications - including clusters.
http://p.sf.net/sfu/intel-dev2devmay
_______________________________________________
Geotools-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/geotools-devel
