Hi Jody, I just ran the tag updater on gt-api but when I checked the resulting javadocs the module listing was missing for some classes. It turned out the header javadocs for those classes had an existing @source tag that had been incorrectly split across lines, so I'll add a check for that to the updater.
Michael On 24 May 2011 00:53, Jody Garnett <[email protected]> wrote: > 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 > > ------------------------------------------------------------------------------ vRanger cuts backup time in half-while increasing security. With the market-leading solution for virtual backup and recovery, you get blazing-fast, flexible, and affordable data protection. Download your free trial now. http://p.sf.net/sfu/quest-d2dcopy1 _______________________________________________ Geotools-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/geotools-devel
