sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r871254 - in /websites/staging/sis/trunk/content: ./ source.html
Date Fri, 26 Jul 2013 09:46:40 GMT
Author: buildbot
Date: Fri Jul 26 09:46:40 2013
New Revision: 871254

Staging update by buildbot for sis

    websites/staging/sis/trunk/content/   (props changed)

Propchange: websites/staging/sis/trunk/content/
--- cms:source-revision (original)
+++ cms:source-revision Fri Jul 26 09:46:40 2013
@@ -1 +1 @@

Modified: websites/staging/sis/trunk/content/source.html
--- websites/staging/sis/trunk/content/source.html (original)
+++ websites/staging/sis/trunk/content/source.html Fri Jul 26 09:46:40 2013
@@ -112,12 +112,14 @@ For fetching the source code, choose one
 <li><a href="#formatting">Code formatting</a><ul>
+<li><a href="#javadoc-tags">Javadoc annotations</a></li>
 <li><a href="#html">HTML elements</a></li>
 <li><a href="#paragraph">Paragraphs</a></li>
 <li><a href="#css">Javadoc CSS</a></li>
 <li><a href="#miscellaneous">Miscellaneous</a></li>
+<li><a href="#classes-naming">Classes naming</a></li>
@@ -247,6 +249,15 @@ Formatting the code in a way that emphas
 aligning identical terms in columns, can help to understand the overall pattern
 and to identify bugs. The decision to use standard or tabular format is made on
 a case-by-case basis. Of course, tabular format shall not be abused.</p>
+<h3 id="javadoc-tags">Javadoc annotations</h3>
+<p>SIS uses standard javadoc annotations. The meaning of some tags are refined as below:</p>
+<li><code>@since</code>   - the SIS version when the annotated element
(class, method, <i>etc.</i>) was first introduced.</li>
+<li><code>@version</code> - the last SIS version when the code of the annotated
class got a significant change.</li>
+<li><code>@author</code>  - developer name in <var>FirstName</var>
<var>LastName</var> (<var>Organization</var>) format.
+                 A separated <code>@author</code> tag is added for each developer.
+                 The intend is to allow other developers to know to who to ask questions
if needed.</li>
 <h3 id="html">HTML elements</h3>
 <p>HTML tags and entities shall be used only when there is no equivalent Javadoc tag.
 In addition to the standard Javadoc tags, a few <a href="">SIS-specific
Javadoc tags</a> are available.
@@ -321,6 +332,12 @@ Instead, rely on styling. Some HTML tags
 <li><strong>Line wrapping:</strong> Use 120-column line width for Java
code and Javadoc.
     Some exceptions to this rule may exist for preserving tabular structures, but should
be rare.</li>
+<h2 id="classes-naming">Classes naming</h2>
+<p>Implementations of GeoAPI interfaces usually (but not always) begin with <code>Abstract</code>,
<code>Default</code>, <code>Simple</code> or <code>General</code>
+The <code>Abstract</code> prefix is used when a class is abstract according <abbr
title="International Organization for Standardization">ISO</abbr> specifications
- it may or may not be be abstract in the Java sense.
+The <code>General</code> prefix is used when an implementation is designed for
use in the general case,
+as opposed to other implementations specialized for a fixed number of dimensions or other
+Implementations specialized for a fixed number of dimensions are suffixed with <code>1D</code>,
<code>2D</code>, <code>3D</code> or <code>4D</code> rather
than being prefixed.</p>

View raw message