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
