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

[ben@openlaszlo.org]

Author: ben
Date: 2007-12-09 20:30:44 -0800 (Sun, 09 Dec 2007)
New Revision: 7492

Modified:
   openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/JS2DocUtils.java
   openlaszlo/trunk/docs/src/xsl/js2doc2dbk/synopsis.xsl
   openlaszlo/trunk/docs/src/xsl/js2doc2dbk/utilities.xsl
Log:
Change 20071209-ben-o by ben at slim.local on 2007-12-09 20:14:20 PST
    in /Users/ben/src/svn/openlaszlo/trunk
    for http://svn.openlaszlo.org/openlaszlo/trunk

Summary: Don't issue so many unnecessary warnings in the doc build

Technical Reviewer: none

Documentation:

The js2doc build was issuing the same error over and over: 
WARNING: Unexpected number of child nodes in ... 
I changed this to be a "fine" log message, rather than a warning. 
Now if we want to see it, we just set the log level to Level.FINE, 
but we don't have to see it otherwise. 

Similarly, there were lots of messages during the js2doc2dbk step of the
build regarding unknown types:
    Warning! No jstype found for xxxx
and 
    Warning! No class name found for function synopsis: xxx.xxx.xxx

These are now toggled off with several parameters, set in these files:
in utilities.xsl: 
    <xsl:param name="warn.unspecified.lzxtypes" select="0" />
    <xsl:param name="warn.unspecified.jstypes" select="0" />
In synopsis.xsl
    <xsl:param name="warn.classname.not.found" select="0" />  
    
These circumstances are visible in the reference itself as empty
entries in the Type (tag) and Type (js) columns of the attributes
list. The "no class name found" error is visible in the methods
list in the reference guide. Beneath the name of the method,
it's supposed to say className.methodName( params... ) but for the
cases that used to trigger warnings, it does not prepend a 
class name. 

Tests:
ant build doc 
notice that there are hundreds fewer errors than before. 



Modified: openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/JS2DocUtils.java
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/JS2DocUtils.java	2007-12-10 04:29:18 UTC (rev 7491)
+++ openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/JS2DocUtils.java	2007-12-10 04:30:44 UTC (rev 7492)
@@ -275,10 +275,11 @@
 
     static void checkChildrenLowerBounds(SimpleNode node, int min, int expectedMax, String methodName) {
         SimpleNode[] children = node.getChildren();
+
         if (children.length < min) {
             logger.throwing("JS2Doc", methodName, new InternalError("Too few child nodes in " + node.getClass().getName(), node));
         } else if (expectedMax > 0 && children.length > expectedMax) {
-            logger.warning("Unexpected number of child nodes in " + node.getClass().getName());
+            logger.fine("Unexpected number of child nodes in " + node.getClass().getName());
         }
     }
 

Modified: openlaszlo/trunk/docs/src/xsl/js2doc2dbk/synopsis.xsl
===================================================================
--- openlaszlo/trunk/docs/src/xsl/js2doc2dbk/synopsis.xsl	2007-12-10 04:29:18 UTC (rev 7491)
+++ openlaszlo/trunk/docs/src/xsl/js2doc2dbk/synopsis.xsl	2007-12-10 04:30:44 UTC (rev 7492)
@@ -27,6 +27,7 @@
     <xsl:import href="utilities.xsl"/>
 
     <xsl:param name="visibility.filter" select="'public'"/>
+    <xsl:param name="warn.classname.not.found" select="0" />  
 
     <!-- SYNOPSIS -->
 
@@ -175,9 +176,11 @@
                 <!-- For instance methods, show the name of the class --> 
                 <xsl:value-of select="ancestor::property/doc/tag[@name='lzxname']/text"/>.<xsl:value-of select="@name"/>
               </xsl:when>
-               <xsl:otherwise>                 
-                 <xsl:message>No class name found for function synopsis: <xsl:value-of select="@id"/></xsl:message>
-                 <xsl:value-of select="@name"/>
+               <xsl:otherwise>        
+                 <xsl:if test="$warn.classname.not.found">
+                   <xsl:message>No class name found for function synopsis: <xsl:value-of select="@id"/></xsl:message>
+                 </xsl:if>                   
+                 <xsl:value-of select="@name"/>                                    
                </xsl:otherwise>
               </xsl:choose>                
             </methodname>

Modified: openlaszlo/trunk/docs/src/xsl/js2doc2dbk/utilities.xsl
===================================================================
--- openlaszlo/trunk/docs/src/xsl/js2doc2dbk/utilities.xsl	2007-12-10 04:29:18 UTC (rev 7491)
+++ openlaszlo/trunk/docs/src/xsl/js2doc2dbk/utilities.xsl	2007-12-10 04:30:44 UTC (rev 7492)
@@ -24,6 +24,9 @@
 
 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 
+    <xsl:param name="warn.unspecified.lzxtypes" select="0" />
+    <xsl:param name="warn.unspecified.jstypes" select="0" />
+  
     <xsl:key name="name-js" match="property" use="@name"/>
     <xsl:key name="name-lzx" match="property" use="&tagname;"/>
 
@@ -58,6 +61,9 @@
         </xsl:when>
         <xsl:otherwise>
           <xsl:text>?lzxtype?</xsl:text>
+          <xsl:if test="$warn.unspecified.lzxtypes">
+            <xsl:message>No lzxtype found for <xsl:value-of select="@name"/></xsl:message>
+          </xsl:if>  
         </xsl:otherwise>
       </xsl:choose>
     </xsl:template>
@@ -76,8 +82,10 @@
           </xsl:element>
         </xsl:when>
         <xsl:otherwise>
-          <!-- We couldn't find a type for this. -->
-          <xsl:message>No type found for <xsl:value-of select="@name"/></xsl:message>
+          <xsl:if test="$warn.unspecified.jstypes">
+            <!-- We couldn't find a type for this. -->
+            <xsl:message>No jstype found for <xsl:value-of select="@name"/></xsl:message>
+          </xsl:if>            
         </xsl:otherwise>
       </xsl:choose>
     </xsl:template>