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

[P T Withington]

Approved!

On 2008-06-26, at 11:17 EDT, dda at openlaszlo.org wrote:

> 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>
>
>
> _______________________________________________
> Laszlo-checkins mailing list
> Laszlo-checkins at openlaszlo.org
> http://www.openlaszlo.org/mailman/listinfo/laszlo-checkins