[Laszlo-dev] For Review: Change 20081031-dda-X Summary: Fix/remove most warnings from schema builder

[P T Withington]

Just a few comments:

1) I know you want to make this change safe by changing only doc not  
code, but this:

-  * @param String js: Browser javascript to execute
+  * @param args: Browser javascript to execute
    */
  static function callJS (...args) {
      var js = args[0];

really bugs me.  The documentation change is inaccurate, because it  
does not document what the function does.  Although what the point of  
accepting any number of arguments and then only using the first one  
is, I don't know.  If you can't figure this out, I guess you should  
file a bug.  And, since this is in platform-specific kernel code, it  
probably should be marked private and not documented at all?

2) It's really annoying that the doc tool forces you to write bad  
documentation:

-   * @param string control: A control string where % indicates a
-   * subsequent argument is to be substituted
-   *
-   * @param Array * args: Any number of arguments to be formatted
-   * according to the control string
+   * @param Array * args: The first argument is a control string
+   * where % indicates a subsequent argument is to be substituted.
+   * Following this are any number of arguments to be formatted
+   * according to the control string.

I know (as the designer) that although the Debug.debug/info/warn/error  
methods take just a single ...rest arg (because they are just going to  
trampoline it on to an internal implementation), they act as if they  
take a first arg that is a string followed by a ...rest arg.  And I  
know that conveys the API much more transparently than the re-write.   
If the doc tool really has to be Draconian, I would rather change the  
code to take `(control:String ...args)` and then concat them together  
in the internal apply, than to have to fudge the prose.  Maybe there  
could be an `@keywords iknowwhatiamdoing` pragma to disable this  
"feature" of the doc tool?

---

Otherwise, approved.

On 2008-11-01, at 08:17EDT, Donald Anderson wrote:

> Change 20081031-dda-X by dda at lester.local on 2008-10-31 13:10:24 EDT
>    in /Users/dda/laszlo/src/svn/openlaszlo/trunk-doc5
>    for http://svn.openlaszlo.org/openlaszlo/trunk
>
> Summary: Fix/remove most warnings from schema builder
>
> New Features:
>
> Bugs Fixed: LPP-3508
>
> Technical Reviewer: ptw (pending)
> QA Reviewer: (pending)
> Doc Reviewer: (pending)
>
> Documentation:
>
> Release Notes:
>
> Details:
>   Several kinds of warnings have been produced by the schema builder.
>   1) Many were not real:
>
>     [java] Warning: attribute LzHTTPDataProvider.prototype has no  
> @lzxtype or @type in javadoc, needed for schema
>     [java] Warning: attribute LzHTTPDataRequest.__ivars__ has no  
> @lzxtype or @type in javadoc, needed for schema
>
>   __ivars__ and prototype are used as names internally in the doc  
> and never represent attributes that
>   need to be documented for the schema.  So these messages are now  
> repressed.
>
>   2) Two sets of messages like so:
>     [java] WARNING: ignoring unknown initializer type:  
> org.openlaszlo.sc.parser.ASTAssignmentExpression
>     [java] node: (0>>0)  
> org.openlaszlo.sc.parser.ASTAssignmentExpression  (null: 167, 18)
>     [java] node: (1>>0)  
> org.openlaszlo.sc.parser.ASTPropertyIdentifierReference  (null: 167,  
> 20)
>     [java] node: (2>>0) org.openlaszlo.sc.parser.ASTIdentifier ii  
> (null: 167, 18)
>     [java] node: (2>>1) org.openlaszlo.sc.parser.ASTIdentifier name  
> (null: 167, 21)
>     [java] node: (1>>1) org.openlaszlo.sc.parser.ASTOperator  (null:  
> 167, 26)
>     [java] node: (1>>2) org.openlaszlo.sc.parser.ASTLiteral Instance  
> (null: 167, 28)
>
>   Represent a global var statement that was initialized:
>    if ($profile) {
>       var ii = Instance.initialize;
>       ii._dbg_name = ii.name = 'Instance.initialize';
>    }
>   Whether or not globals could be initialized without warning was  
> not addressed.  In this
>   case, it seemed clear that the introduction of the global 'ii' was  
> a mistake, so
>   these lines were rewritten without using a variable.
>
>   3) A larger number of errors represent variable names misnamed in  
> the documentation, or
>      when @param name type:   was used instead of @param type name:
>
>     [java] Oct 31, 2008 1:04:59 PM  
> org.openlaszlo.js2doc.ReprocessComments$ParamFieldFilter handleField
>     [java] WARNING: Couldn't find parameter named view in  
> LzSelectionManager.prototype.construct
>
>     These have been corrected by preferring the names actually used  
> in the code.
>
>
>   These changes expose a much smaller set of warnings about missing  
> type information in javadoc
>   that is actually needed for a correct schema.
>
> Tests:
>   smokecheck (swf8, dhtml)
>   weather (all)
>   lzpix (all)
>   hello (swf9)
>
> Files:
> M      WEB-INF/lps/lfc/kernel/swf/LzMakeLoadSprite.as
> M      WEB-INF/lps/lfc/kernel/swf9/LzBrowserKernel.lzs
> M      WEB-INF/lps/lfc/services/LzBrowser.lzs
> M      WEB-INF/lps/lfc/debugger/LzDebug.lzs
> M      WEB-INF/lps/lfc/debugger/platform/dhtml/LzDebug.js
> M      WEB-INF/lps/lfc/debugger/LzMemory.lzs
> M      WEB-INF/lps/lfc/helpers/LzSelectionManager.lzs
> M      WEB-INF/lps/lfc/data/LzReplicationManager.lzs
> M      WEB-INF/lps/lfc/data/LzDataset.lzs
> M      WEB-INF/lps/lfc/compiler/LzBootstrapDebugService.lzs
> M      WEB-INF/lps/lfc/compiler/Class.lzs
> M      WEB-INF/lps/server/src/org/openlaszlo/js2doc/SchemaBuilder.java
>
> Changeset: http://svn.openlaszlo.org/openlaszlo/patches/20081031-dda-X.tar
>
>
>
> --
>
> Don Anderson
> Java/C/C++, Berkeley DB, systems consultant
>
> voice: 617-547-7881
> email: dda at ddanderson.com
> www: http://www.ddanderson.com
>
>
>