Repository: commons-text Updated Branches: refs/heads/master 38ceb4706 -> ae91d3c51
TEXT-53: adding developerguide based on lang's Project: http://git-wip-us.apache.org/repos/asf/commons-text/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-text/commit/ae91d3c5 Tree: http://git-wip-us.apache.org/repos/asf/commons-text/tree/ae91d3c5 Diff: http://git-wip-us.apache.org/repos/asf/commons-text/diff/ae91d3c5 Branch: refs/heads/master Commit: ae91d3c51a28486d2e3938cdeded9900d42cd3bc Parents: 38ceb47 Author: Rob Tompkins <[email protected]> Authored: Mon Jan 2 13:21:45 2017 -0500 Committer: Rob Tompkins <[email protected]> Committed: Mon Jan 2 13:21:45 2017 -0500 ---------------------------------------------------------------------- src/site/xdoc/developerguide.xml | 151 ++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-text/blob/ae91d3c5/src/site/xdoc/developerguide.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/developerguide.xml b/src/site/xdoc/developerguide.xml new file mode 100644 index 0000000..58f687c --- /dev/null +++ b/src/site/xdoc/developerguide.xml @@ -0,0 +1,151 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> +<document> + <properties> + <title>Developer guide for Commons "Text"</title> + </properties> + <body> + + <!-- $Id$ --> + + <section name='Developer guide for Commons "Text"'> + + <h1>The Commons <em>Text</em> Package</h1> + <h2>Developers Guide</h2> + <br /> + <a href="#Introduction">[Introduction]</a> + <a href="#PackageStructure">[Package Structure]</a> + <a href="#UtilityClasses">[Utility Classes]</a> + <a href="#Javadoc">[Javadoc]</a> + <a href="#Building">[Building]</a> + <br /><br /> + + <a name="Introduction"></a> + <h3>1. INTRODUCTION</h3> + + <p>The <em>Text</em> package contains a set of Java classes that contain algorithms for measuring + and manipulating string. This developer guide seeks to set + out rules for the naming of classes and methods within the package. The purpose + of this, as with all naming standards, is to improve the coherency and + consistency of the whole API.</p> + + <p>The philosophy of the naming standards is to follow those of the JDK + if possible.</p> + + + + <a name="PackageStructure"></a> + <h3>2. PACKAGE STRUCTURE</h3> + + <p>The main package for Text is <code>org.apache.commons.text</code>. Subpackages should + be created for each group of related items. </p> + + <p>Each package should have a <code>package.html</code> file for javadoc. This should + describe the use of the package and its scope.</p> + + + + <a name="UtilityClasses"></a> + <h3>3. UTILITY CLASSES</h3> + + <p>Utility classes provide additional functionality around a class or interface. + Examples include StringUtils and StringEscapeUtils.</p> + + <p>Each class shall follow the naming pattern XxxUtils where Xxx relates to the + class or interface that the utility services. Variations on a theme (<code>Integer</code> + as opposed to <code>Number</code>) should be dealt with in one Utils class where possible. + Each Utils class shall:</p> + + <ul> + <li>be a single, static method based, class</li> + <li>have a name consisting of the interface name plus 'Utils'</li> + <li>deal with one class or interface and its variations (subclasses)</li> + <li>provide methods that perform useful utility functions</li> + <li>the class will not be final</li> + <li>for null parameters, rather than throwing an Exception, consider performing a Null patterned concept, such as returning 0 or ""</li> + </ul> + + <p>A utility class can act as a factory for specific implementations of a class or + interface. In such cases the implementations should be non-public, static, inner classes + of the utility class. However, if warranted due to maintenance or other reasons, these + decorator classes may be moved to top-level classes in a subpackage. The + naming of such a subpackage should be discussed and agreed upon on the + developers mailing list.</p> + + <p>If different overloaded variants of a method are desired, with the same method signature, it should not be indicated via a boolean argument, but via a more focused method name. Rather than replace(boolean repeat), replace and replaceAll, or replaceOnce and replace. </p> + + + <a name="Javadoc"></a> + <h3>4. JAVADOC</h3> + + <p>The Sun javadoc guidelines are the starting point for Text. These points are + an extension to make it easier for users reading the generated + docs and developers with javadoc-popup capabilities from within their IDE.</p> + + <h4>General</h4> + <p>References to other objects, interfaces or methods use the @link-tag the + first time it is referenced in a class or interface. On the following + references always enclose it inside <code></code>.</p> + + <p>References to <code>null</code>, <code>this</code>, <code>long</code>, + <code>int</code>, <code>short</code>, <code>char</code>, <code>byte</code>, + <code>double</code>, <code>float</code> and <code>boolean</code> should be enclosed + in <code></code>.</p> + + <h4>Classes/Interfaces/Methods</h4> + <p>Use a short description of what the class/interface/method is used for, + enclose with <p></p>.</p> + + <p>A longer description about what the class/interface/method is used for + and if it is needed how it is done. If it is necessary include + description of the parameters, what they are used for and how. Enclose + with <p></p> where it is needed, try to divide into smaller parts (not + to small!) to enhance readability of the generated Javadoc.</p> + + <p>If an example is needed enclose it with <pre></pre>. + It should be supported with an explanation within a normal paragraph.</p> + + <h4>Exception throwing</h4> + <p>When throwing an exception to indicate a bad argument, always try to throw + IllegalArgumentException, even if the argument was null. Do not throw + NullPointerException. (Obviously, you should document what the code actually does!)</p> + + <h4>Deprecations</h4> + <p>When deprecating a method or class include a clear reference to when the method will be deleted. + This should be of the form 'Method will be removed in Commons Text 2.0.'. </p> + + <h4>Language used in code/comments</h4> + <p>It has been decided to casually standardize on US-English. + To avoid misplaced jeers of 'americanisation', the people making this decision largely write in non-US-English. + However, it's not something to get worked up about. Lots of spelling differences will creep in all over.</p> + + <a name="Building"></a> + <h3>5.BUILDING</h3> + <h4>Building a Release</h4> + <p> + The currently targeted version of Java is 1.7. + </p> + <p> + To build Text: + <table> + <tr><th></th><th>Tested JAR</th><th>Distribution</th><th>Site</th></tr> + <tr><td>Maven 3.x</td><td><code>mvn package</code></td><td>mvn assembly:assembly</td><td>mvn site</td></tr> + </table> + </p> + </section> + </body> +</document> \ No newline at end of file
