Changes between Version 4 and Version 5 of DeveloperGuidelines
- Timestamp:
- Feb 8, 2011, 10:53:10 AM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
DeveloperGuidelines
v4 v5 5 5 ==SVN Keyword Expansion / Substitution== 6 6 All 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 {{{ 8 8 /** 9 9 ... regular doc ... … … 14 14 * $Rev* 15 15 */ 16 </source> 16 }}} 17 17 Keyword 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 19 20 $ svn propset svn:keywords "Date Author Rev" myClass.groovy 20 </code> 21 }}} 21 22 22 23 ==Descriptions== … … 24 25 The 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. 25 26 This 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 {{{ 27 28 /** 28 29 * This is a simulation of Prof. Knuth's MIX computer. 29 30 */ 30 </source> 31 }}} 31 32 32 33 However, you can work around this by typing an HTML meta-character such as "&" or "<" immediately after the period, such as: 33 34 34 <source lang="groovy"> 35 {{{ 35 36 /** 36 37 * This is a simulation of Prof. Knuth's MIX computer. 37 38 */ 38 </source> 39 }}} 39 40 40 41 or 41 42 42 <source lang="groovy"> 43 {{{ 43 44 /** 44 45 * This is a simulation of Prof.<!-- --> Knuth's MIX computer. 45 46 */ 46 </source> 47 }}} 47 48 48 49 In particular, write summary sentences that distinguish overloaded methods from each other. For example: 49 <source lang="groovy"> 50 {{{ 50 51 /** 51 52 * Class constructor. … … 59 60 foo(int n) { 60 61 ... 61 </source> 62 }}} 62 63 63 64 ==Tag Conventions== 64 65 ===Order of Tags=== 65 66 Include tags in the following order: 66 <source lang="java"> 67 {{{ 67 68 * @author (classes and interfaces only, required) 68 69 * @version (classes and interfaces only, required. See footnote 1) … … 74 75 * @serial (or @serialField or @serialData) 75 76 * @deprecated (see How and When To Deprecate APIs) 76 </source> 77 }}} 77 78 78 79 ===Ordering Multiple Tags=== … … 86 87 87 88 Multiple @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 {{{ 89 90 @see #field 90 91 @see #Constructor(Type, Type...) … … 105 106 @see package.Class#method(Type id, Type, id) 106 107 @see package 107 </source> 108 }}} 108 109 ===Required Tags=== 109 110 An @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.)
