Changes between Version 4 and Version 5 of DeveloperGuidelines

Show
Ignore:
Timestamp:
08-02-11 10:53:10 (3 years ago)
Author:
jannekevdp@…
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidelines

    v4 v5  
    55==SVN Keyword Expansion / Substitution== 
    66All files should contain revision information using SVN [http://svnbook.red-bean.com/en/1.4/svn.advanced.props.special.keywords.html SVN Keyword Expansion / Keyword Substition] (svn:keywords Date Rev Author). Example lines to include in the documentation: 
    7 <source lang="java"> 
     7{{{ 
    88/** 
    99  ... regular doc ... 
     
    1414  * $Rev* 
    1515  */ 
    16 </source> 
     16}}} 
    1717Keyword expansion must be manually defined on a per-file basis. Possibly your SVN IDE integration or stand alone client will be capable of recusively setting these keywords, and you can also do it yourself manually: 
    18 <code> 
     18{{{ 
     19 
    1920$ svn propset svn:keywords "Date Author Rev" myClass.groovy 
    20 </code> 
     21}}} 
    2122 
    2223==Descriptions== 
     
    2425The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the API item. This means the first sentence of each member, class, interface or package description. The Javadoc tool copies this first sentence to the appropriate member, class/interface or package summary. This makes it important to write crisp and informative initial sentences that can stand on their own. 
    2526This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag (as defined below). For example, this first sentence ends at "Prof.": 
    26 <source lang="groovy"> 
     27{{{ 
    2728/** 
    2829  * This is a simulation of Prof. Knuth's MIX computer. 
    2930  */ 
    30 </source> 
     31}}} 
    3132 
    3233However, you can work around this by typing an HTML meta-character such as "&" or "<" immediately after the period, such as: 
    3334 
    34 <source lang="groovy"> 
     35{{{ 
    3536/** 
    3637  * This is a simulation of Prof.&nbsp;Knuth's MIX computer. 
    3738  */ 
    38 </source> 
     39}}} 
    3940 
    4041or 
    4142 
    42 <source lang="groovy"> 
     43{{{ 
    4344/** 
    4445  * This is a simulation of Prof.<!-- --> Knuth's MIX computer. 
    4546  */ 
    46 </source> 
     47}}} 
    4748 
    4849In particular, write summary sentences that distinguish overloaded methods from each other. For example: 
    49 <source lang="groovy"> 
     50{{{ 
    5051/**  
    5152  * Class constructor. 
     
    5960  foo(int n) { 
    6061   ... 
    61 </source> 
     62}}} 
    6263 
    6364==Tag Conventions== 
    6465===Order of Tags=== 
    6566Include tags in the following order: 
    66 <source lang="java"> 
     67{{{ 
    6768* @author      (classes and interfaces only, required) 
    6869* @version     (classes and interfaces only, required. See footnote 1) 
     
    7475* @serial      (or @serialField or @serialData) 
    7576* @deprecated  (see How and When To Deprecate APIs) 
    76 </source> 
     77}}} 
    7778 
    7879===Ordering Multiple Tags=== 
     
    8687 
    8788Multiple @see tags should be ordered as follows, which is roughly the same order as their arguments are searched for by javadoc, basically from nearest to farthest access, from least-qualified to fully-qualified, The following list shows this progression. Notice the methods and constructors are in "telescoping" order, which means the "no arg" form first, then the "1 arg" form, then the "2 arg" form, and so forth. Where a second sorting key is needed, they could be listed either alphabetically or grouped logically. 
    88 <source lang="java"> 
     89{{{ 
    8990   @see #field 
    9091   @see #Constructor(Type, Type...) 
     
    105106   @see package.Class#method(Type id, Type, id) 
    106107   @see package 
    107 </source> 
     108}}} 
    108109===Required Tags=== 
    109110An @param tag is "required" (by convention) for every parameter, even when the description is obvious. The @return tag is required for every method that returns something other than void, even if it is redundant with the method description. (Whenever possible, find something non-redundant (ideally, more specific) to use for the tag comment.)