[Laszlo-checkins] r10016 - in openlaszlo/trunk: WEB-INF/lps/server/src/org/openlaszlo/js2doc docs/src/xsl/js2doc2dbk

[dda@openlaszlo.org]

Author: dda
Date: 2008-06-26 08:17:13 -0700 (Thu, 26 Jun 2008)
New Revision: 10016

Modified:
   openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/ReprocessComments.java
   openlaszlo/trunk/docs/src/xsl/js2doc2dbk/synopsis.xsl
Log:
Change 20080626-dda-b by dda at lester.local on 2008-06-26 10:36:09 EDT
    in /Users/dda/laszlo/src/svn/openlaszlo/trunk-doc5
    for http://svn.openlaszlo.org/openlaszlo/trunk

Summary: Fixed ... type notation for documentation

New Features:

Bugs Fixed: LPP-5872 (Doc tools fail for *, |, and [] in parameter type) 

Technical Reviewer: ptw (pending)
QA Reviewer: (pending)
Doc Reviewer: liorio (pending)

Documentation:

Release Notes:

Details:
  Parse optional ... into a separate regexp group, and pass it through
  as part of the type, rather than the name.  This allows the name to
  match the parameter names actually seen in the JS source, and besides
  it seems logical.  ... is shown as part of the type in the attribute
  table, but the synopsis is made to match the Javascript.

  As an example, using this javadoc:
   /**
    * javadoc for someFunction
    * @param LzView foo: some text
    * @param ...rest: some other text
    */
   function someFunction (foo, ...rest)

  you'll get output:

    someClass.someFunction(foo : LzView, ...rest);
    javadoc for someFunction

    Parameter Name    Type        Description
    foo               LzView      some text
    rest              ...         some other text
    

Tests:
    Added example function above and verified.
    Also rebuilt docs for scratch and do quick check for regressions.
    Also verified that '|' works in types, see LzView.setVisible()



Modified: openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/ReprocessComments.java
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/ReprocessComments.java	2008-06-26 15:16:42 UTC (rev 10015)
+++ openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/ReprocessComments.java	2008-06-26 15:17:13 UTC (rev 10016)
@@ -185,7 +185,7 @@
     
         // TODO [jgrandy 12/14/2006] use Java5's Scanner instead of regexp here
         
-        static private final Pattern paramPattern  = Pattern.compile("^\\s*(?:([\\w\\[\\]\\|\\*]+)\\s+)?([.\\w]*)(?::(.*))?$", Pattern.DOTALL);
+        static private final Pattern paramPattern  = Pattern.compile("^\\s*(?:([\\w\\[\\]\\|\\*]+)\\s+)?(?:(\\.\\.\\.))?(\\w*)(?::(.*))?$", Pattern.DOTALL);
         static private final Pattern returnPattern = Pattern.compile("^\\s*([\\w\\[\\]\\|\\*]+)(?::(.*))?$", Pattern.DOTALL);
     
         public ParamFieldFilter(CommentFieldFilter nextFilter) {
@@ -200,9 +200,16 @@
                 boolean found = valueMatcher.find();
                 if (found) {
                     String paramType = valueMatcher.group(1),
-                           paramName = valueMatcher.group(2),
-                           paramDesc = valueMatcher.group(3);
-                    
+                           paramDots = valueMatcher.group(2),
+                           paramName = valueMatcher.group(3),
+                           paramDesc = valueMatcher.group(4);
+
+                    // Indicate optional args in the type string
+                    if ("...".equals(paramDots)) {
+                        paramType = (paramType == null) ? "" : paramType;
+                        paramType += "...";
+                    }
+
                     // now find the appropriate parameter node in the DOM node
                     String tagName = node.getTagName();
                     org.w3c.dom.Element functionNode = 

Modified: openlaszlo/trunk/docs/src/xsl/js2doc2dbk/synopsis.xsl
===================================================================
--- openlaszlo/trunk/docs/src/xsl/js2doc2dbk/synopsis.xsl	2008-06-26 15:16:42 UTC (rev 10015)
+++ openlaszlo/trunk/docs/src/xsl/js2doc2dbk/synopsis.xsl	2008-06-26 15:17:13 UTC (rev 10016)
@@ -190,8 +190,19 @@
         </xsl:choose>
         <xsl:for-each select="function/parameter">
           <methodparam>
-            <parameter><xsl:value-of select="@name"/></parameter>
-            <xsl:if test="@type"><type role="javascript"><xsl:value-of select="@type"/></type></xsl:if>
+            <!-- The 'type' may end with ... for optional args.  For the
+                 synopsis, we want to prefix the name to match JS syntax -->
+            <xsl:choose>
+              <xsl:when test="contains(@type, '...')">
+                <parameter><xsl:value-of select="concat('...', @name)"/></parameter>
+                <xsl:variable name="printable-type" select="substring-before(@type, '...')"/>
+                <xsl:if test="$printable-type"><type role="javascript"><xsl:value-of select="$printable-type"/></type></xsl:if>
+              </xsl:when>
+              <xsl:otherwise>
+                <parameter><xsl:value-of select="@name"/></parameter>
+                <xsl:if test="@type"><type role="javascript"><xsl:value-of select="@type"/></type></xsl:if>
+              </xsl:otherwise>
+            </xsl:choose>
           </methodparam>
         </xsl:for-each>        
       </methodsynopsis>