Merge pull request SalesforceFoundation#46 from openback/example-tag

@example tag

.gitignore

@@ -0,0 +1 @@
+/target

README.md

@@ -19,12 +19,12 @@ ApexDoc was originally created by Aslam Bari (http://techsahre.blogspot.com/2011
 ## Usage
 Copy apexdoc.jar file to your local machine, somewhere on your path.  Each release tag in gitHub has the matching apexdoc.jar attached to it.  Make sure that java is on your path.  Invoke ApexDoc like this example:
 ```
-java -jar apexdoc.jar 
-    -s '/Users/dhabib/Workspaces/Force.com IDE/Cumulus3/src/classes' 
-    -t '/Users/dhabib/Dropbox/Cumulus/ApexDoc' 
-    -p 'global;public;private;testmethod;webService' 
-    -h '/Users/dhabib/Dropbox/Cumulus/ApexDoc/homepage.htm' 
-    -a '/Users/dhabib/Dropbox/Cumulus/ApexDoc/projectheader.htm' 
+java -jar apexdoc.jar
+    -s '/Users/dhabib/Workspaces/Force.com IDE/Cumulus3/src/classes'
+    -t '/Users/dhabib/Dropbox/Cumulus/ApexDoc'
+    -p 'global;public;private;testmethod;webService'
+    -h '/Users/dhabib/Dropbox/Cumulus/ApexDoc/homepage.htm'
+    -a '/Users/dhabib/Dropbox/Cumulus/ApexDoc/projectheader.htm'
     -g 'http://github.com/SalesforceFoundation/Cumulus/blob/dev/src/classes/'
 ```
 
@@ -69,7 +69,7 @@ Example
     /*******************************************************************************************************
     * @description specifies whether state and country picklists are enabled in this org.
     * returns true if enabled.
-    */ 
+    */
     public static Boolean isStateCountryPicklistsEnabled {
         get {
 ```
@@ -82,13 +82,16 @@ In order for ApexDoc to identify class methods, the method line must contain an
 | @description | one or more lines that provide an overview of the method|
 | @param *param name* | a description of what the parameter does|
 | @return | a description of the return value from the method|
+| @example | Example code usage. This will be wrapped in <code> tags to preserve whitespace|
 Example
 ```
     /*******************************************************************************************************
-    * @description Returns field describe data 
+    * @description Returns field describe data
     * @param objectName the name of the object to look up
     * @param fieldName the name of the field to look up
     * @return the describe field result for the given field
-    */ 
+    * @example
+    * Account a = new Account();
+    */
     public static Schema.DescribeFieldResult getFieldDescribe(String objectName, String fieldName) {
 ```

pom.xml

@@ -2,12 +2,12 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>ApexDoc</groupId>
   <artifactId>ApexDoc</artifactId>
-  <version>1.1.5-SNAPSHOT</version>
+  <version>1.2.0-SNAPSHOT</version>
   <name>ApexDoc</name>
   <description>A documentation generator for Apex using JavaDoc style comment blocks</description>
-  
+
   <packaging>jar</packaging>
-  
+
   <build>
     <sourceDirectory>src</sourceDirectory>
     <resources>
@@ -45,4 +45,4 @@
 	  </plugin>
     </plugins>
   </build>
-</project>
+</project>

src/org/salesforce/apexdoc/ApexDoc.css

@@ -69,7 +69,7 @@ body {
 
 /* properties is used to display the table of class properties */
 .properties {
-    
+
 }
 
 .properties td {
@@ -181,6 +181,13 @@ body {
     margin: 0 0 0 1em;
 }
 
+.methodExample {
+    background-color: #f7f7f7;
+    display: block;
+    padding: 1em;
+    white-space: pre;
+}
+
 /* SIDEBAR CSS */
 div.navbar {
     font-size: .9em;
@@ -283,11 +290,11 @@ li .caret {
 }
 
 div.navbar ul li a.scopeglobal {
-    
+
 }
 
 div.navbar ul li a.scopeprivate {
-    
+
 }
 
-/* END - SIDEBAR STYLES */
+/* END - SIDEBAR STYLES */

src/org/salesforce/apexdoc/ApexDoc.java

@@ -397,6 +397,7 @@ private static void fillPropertyModel(PropertyModel propertyModel, String name,
     private static void fillMethodModel(MethodModel mModel, String name, ArrayList<String> lstComments, int iLine) {
         mModel.setNameLine(name, iLine);
         boolean inDescription = false;
+        boolean inExample = false;
         int i = 0;
         for (String comment : lstComments) {
         	i++;
@@ -406,30 +407,34 @@ private static void fillMethodModel(MethodModel mModel, String name, ArrayList<S
             if (idxStart != -1) {
                 mModel.setAuthor(comment.substring(idxStart + 8).trim());
                 inDescription = false;
+                inExample = false;
                 continue;
             }
 
             idxStart = comment.toLowerCase().indexOf("@date");
             if (idxStart != -1) {
                 mModel.setDate(comment.substring(idxStart + 5).trim());
                 inDescription = false;
+                inExample = false;
                 continue;
             }
 
             idxStart = comment.toLowerCase().indexOf("@return");
             if (idxStart != -1) {
                 mModel.setReturns(comment.substring(idxStart + 7).trim());
                 inDescription = false;
+                inExample = false;
                 continue;
             }
 
             idxStart = comment.toLowerCase().indexOf("@param");
             if (idxStart != -1) {
                 mModel.getParams().add(comment.substring(idxStart + 6).trim());
                 inDescription = false;
+                inExample = false;
                 continue;
             }
-            
+
             idxStart = comment.toLowerCase().indexOf("@description");
             if (idxStart != -1 || i == 1) {
                 if (idxStart != -1 && comment.length() >= idxStart + 12)
@@ -442,19 +447,48 @@ private static void fillMethodModel(MethodModel mModel, String name, ArrayList<S
                 	}
                 }
                 inDescription = true;
+                inExample = false;
                 continue;
             }
 
-            // handle multiple lines for description.
-            if (inDescription) {
+            idxStart = comment.toLowerCase().indexOf("@example");
+            if (idxStart != -1 || i == 1) {
+                if (idxStart != -1 && comment.length() >= idxStart + 8) {
+                    mModel.setExample(comment.substring(idxStart + 8).trim());
+                } else {
+                	Pattern p = Pattern.compile("\\s");
+                	Matcher m = p.matcher(comment.substring(8));
+
+                	if (m.find()) {
+                		mModel.setExample(comment.substring(m.start()).trim());
+                	}
+                }
+                inDescription = false;
+                inExample = true;
+                continue;
+            }
+
+            // handle multiple lines for @description and @example.
+            if (inDescription || inExample) {
                 int j;
                 for (j = 0; j < comment.length(); j++) {
                     char ch = comment.charAt(j);
                     if (ch != '*' && ch != ' ')
                         break;
                 }
                 if (j < comment.length()) {
-                    mModel.setDescription(mModel.getDescription() + ' ' + comment.substring(j));
+                    if (inDescription) {
+                        mModel.setDescription(mModel.getDescription() + ' ' + comment.substring(j));
+                    } else if (inExample) {
+                        // Lets's not include the tag
+                        if (j == 0 && comment.substring(2, 10) == "* @example") {
+                            comment = comment.substring(10);
+                        }
+
+                        mModel.setExample(mModel.getExample()
+                            + (mModel.getExample().trim().length() == 0 ? "" : "\n")
+                            + comment.substring(2));
+                    }
                 }
                 continue;
             }
@@ -499,7 +533,7 @@ private static void fillClassModel(ClassModel cModelParent, ClassModel cModel, S
                 inDescription = false;
                 continue;
             }
-            
+
             idxStart = comment.toLowerCase().indexOf("@description");
             if (idxStart != -1 || i == 1) {
             	if (idxStart != -1 && comment.length() > idxStart + 13)
@@ -533,7 +567,7 @@ private static void fillClassModel(ClassModel cModelParent, ClassModel cModel, S
 
     /*************************************************************************
      * strPrevWord
-     * 
+     *
      * @param str
      *            - string to search
      * @param iSearch
@@ -590,23 +624,23 @@ private static int countChars(String str, char ch) {
      * System.out.println(cModel.getAuthor());
      * System.out.println(cModel.getDescription());
      * System.out.println(cModel.getDate());
-     * 
+     *
      * System.out.println("Properties::::::::::::::::::::::::"); for
      * (PropertyModel property : cModel.getProperties()) {
      * System.out.println(property.getNameLine());
      * System.out.println(property.getDescription()); }
-     * 
+     *
      * System.out.println("Methods::::::::::::::::::::::::"); for (MethodModel
      * method : cModel.getMethods()) {
      * System.out.println(method.getMethodName());
      * System.out.println(method.getAuthor());
      * System.out.println(method.getDescription());
      * System.out.println(method.getDate()); for (String param :
      * method.getParams()) { System.out.println(param); }
-     * 
+     *
      * }
-     * 
+     *
      * }catch (Exception e){ e.printStackTrace(); } }
      */
 
-}
+}

src/org/salesforce/apexdoc/ApexModel.java

@@ -47,6 +47,14 @@ public void setReturns(String returns) {
         this.returns = returns;
     }
 
+    public String getExample() {
+        return example == null ? "" : example;
+    }
+
+    public void setExample(String example) {
+        this.example = example;
+    }
+
     public String getScope() {
         return scope == null ? "" : scope;
     }
@@ -71,5 +79,6 @@ private void parseScope() {
     private String date;
     private String returns;
     private String scope;
+    private String example;
 
-}
+}

src/org/salesforce/apexdoc/FileManager.java

@@ -243,7 +243,7 @@ private String htmlForClassModel(ClassModel cModel, String hostedSourceURL) {
                         if (param != null && param.trim().length() > 0) {
                             Pattern p = Pattern.compile("\\s");
                             Matcher m = p.matcher(param);
-                            
+
                             String paramName;
                             String paramDescription;
                             if (m.find()) {
@@ -268,6 +268,11 @@ private String htmlForClassModel(ClassModel cModel, String hostedSourceURL) {
                     contents += "<div class='methodReturns'>" + escapeHTML(method.getReturns()) + "</div>";
                 }
 
+                if (method.getExample() != "") {
+                    contents += "<div class='methodSubTitle'>Example</div>";
+                    contents += "<code class='methodExample'>" + escapeHTML(method.getExample()) + "</code>";
+                }
+
                 if (method.getAuthor() != "") {
                     contents += "<div class='methodSubTitle'>Author</div>";
                     contents += "<div class='methodReturns'>" + escapeHTML(method.getAuthor()) + "</div>";
@@ -321,13 +326,13 @@ private void createClassGroupContent(TreeMap<String, String> mapFNameToContent,
      * @return String of HTML
      */
     private String getPageLinks(TreeMap<String, ClassGroup> mapGroupNameToClassGroup, ArrayList<ClassModel> cModels) {
-        
+
         // this is the only place we need the list of class models sorted by name.
         TreeMap<String, ClassModel> tm = new TreeMap<String, ClassModel>();
         for (ClassModel cm : cModels)
             tm.put(cm.getClassName().toLowerCase(), cm);
         cModels = new ArrayList<ClassModel>(tm.values());
-        
+
         String links = "<td width='20%' vertical-align='top' >";
         links += "<div class='sidebar'><div class='navbar'><nav role='navigation'><ul id='mynavbar'>";
         links += "<li id='idMenuindex'><a href='.' onclick=\"gotomenu('index.html', event);return false;\" class='nav-item'>Home</a></li>";
@@ -342,7 +347,7 @@ private String getPageLinks(TreeMap<String, ClassGroup> mapGroupNameToClassGroup
             String strGoTo = "onclick=\"gotomenu(document.location.href, event);return false;\"";
             if (cg.getContentFilename() != null)
                 strGoTo = "onclick=\"gotomenu('" + cg.getContentFilename() + ".html" + "', event);return false;\"";
-            links += "<li class='header' id='idMenu" + cg.getContentFilename() + 
+            links += "<li class='header' id='idMenu" + cg.getContentFilename() +
                     "'><a class='nav-item nav-section-title' href='.' " +
                     strGoTo + " class='nav-item'>" + strGroup + "<span class='caret'></span></a></li>";
             links += "<ul>";
@@ -466,4 +471,4 @@ public String parseHTMLFile(String filePath) {
         return "";
     }
 
-}
+}