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>
* SimpleFeat
ure 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
