Author: ben
Date: 2007-11-22 12:49:07 -0800 (Thu, 22 Nov 2007)
New Revision: 7357
Modified:
openlaszlo/trunk/WEB-INF/lps/lfc/helpers/LzState.lzs
openlaszlo/trunk/WEB-INF/lps/lfc/services/LzURL.lzs
openlaszlo/trunk/WEB-INF/lps/lfc/services/platform/swf/LzBrowser.as
openlaszlo/trunk/docs/src/xsl/js2doc2dbk.xsl
openlaszlo/trunk/docs/src/xsl/js2doc2dbk/synopsis.xsl
openlaszlo/trunk/docs/src/xsl/js2doc2dbk/utilities.xsl
openlaszlo/trunk/docs/src/xsl/simple-driver.xsl
Log:
Change 20071122-ben-7 by [EMAIL PROTECTED] on 2007-11-22 12:21:36 PST
in /Users/ben/src/svn/openlaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: Make documentation appear for Debug, LzBrowser (swf and dhtml), etc
New Features: Meaningful stuff in...
http://localhost:8080/trunk/docs/reference/Debug+debug.html
http://localhost:8080/trunk/docs/reference/LzBrowser+dhtml.html
http://localhost:8080/trunk/docs/reference/LzBrowser+swf7+swf8+swf9.html
http://localhost:8080/trunk/docs/reference/LzScript.html
http://localhost:8080/trunk/docs/reference/LzState.html
http://localhost:8080/trunk/docs/reference/LzURL.html
http://localhost:8080/trunk/docs/reference/LzFormatter.html
Bugs Fixed:
LPP-5137 RefGuide: Debug is not documented
LPP-5133 RefGuide: ensure correct documentation of LzBrowser in dhtml and swf
LPP-5138 RefGuide: RefGuide: script is not meaningfully documented
LPP-4933 RefGuide: missing reference pages for <script>
Technical Reviewer: ptw (for lzs only) (no reviewer for xsl)
QA Reviewer: none
Doc Reviewer: max (for LzBrowser documentation)
Documentation:
This change turns back on the flags to make static methods, attributes,
and events appear in the reference. This enables the lion's share of
documentation for LzBrowser, LzUrl, Debug, LzState, script, and more
to show up in the reference, although it had previously been hidden.
This change also lists the known direct subclasses at the very bottom
of the reference page.
Reviewers: please just note that this is an improvement over the current
state of affairs for documenting these classes. This is basically a tools
change; the content changes required to produce entirely correct
documentation will have to wait.
Release Notes:
Details:
LzBrowser.as, LzURL.lzs - mark a few methods private.
LzState.lzs - merge two sequential comments so that js2doc can find the
documentation in the first of those comments. Repeat for each of
__LZapplyArgs, __LZstoreRefs, __LZstoreDelegates
docs/src/xsl/js2doc2dbk.xsl - turn on display of static methods,
attributes, and events. Also turn on displaying the list of known
subclasses at the very end of the reference page.
docs/src/xsl/simple-driver.xsl - more testing help for figuring out
xpaths for static methods
docs/src/xsl/js2doc2dbk/utilities.xsl - Instead of printing ?jstype?
in the reference when we can't find a type, just leave it blank
in the reference, but issue a build warning. For missing lzxtypes,
print ?lzxtype? instead of ???. Now we'll see how many of these
there are, and what the best way to deal is. (There were tons
of ?jstype?s.)
docs/src/xsl/js2doc2dbk/synopsis.xsl - Show method names as
MyClass.myMethodName for static methods. (That format was
already working for instance methods.)
Tests:
See urls in "New Features" above for list of files to test.
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/helpers/LzState.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/helpers/LzState.lzs 2007-11-22
20:48:29 UTC (rev 7356)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/helpers/LzState.lzs 2007-11-22
20:49:07 UTC (rev 7357)
@@ -287,8 +287,8 @@
* state are args that have setters (which will be intercepted by
* __LZstoreRefs, q.v.), hence we can just intercept
* addProperty to capture the 'held args'.
- */
-/* override */ function __LZapplyArgs ( args ){
+ *
+* override */ function __LZapplyArgs ( args ){
var ap = this.addProperty;
this.addProperty = function (prop, val) {
this.heldArgs[prop] = val;
@@ -302,8 +302,7 @@
* Capture setters that don't belong to the state for later
* application to the parent (and pass the ones that do apply to the
* state on to your superclass).
- */
-/* override */ function __LZstoreRefs ( refs, prop ){
+* override */ function __LZstoreRefs ( refs, prop ){
var parrefs = {};
var myrefs = {};
@@ -333,8 +332,7 @@
* Capture handlers that don't belong to the state for later
* application to the parent (and pass the ones that do apply to the
* state on to your superclass).
- */
-/* override */ function __LZstoreDelegates ( delarr ){
+* override */ function __LZstoreDelegates ( delarr ){
var pardels = [];
var mydels = [];
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/services/LzURL.lzs
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/services/LzURL.lzs 2007-11-22 20:48:29 UTC
(rev 7356)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/services/LzURL.lzs 2007-11-22 20:49:07 UTC
(rev 7357)
@@ -130,6 +130,7 @@
/foo/bar/baz/foo.html := "/foo/bar/baz/", "foo.html"
/foo/bar/ := "/foo/bar/", null
foo.html := null, "foo.html"
+ @access private
*/
LzURL.prototype._splitPath = function(pathfile)
{
@@ -153,7 +154,7 @@
}
-// @keywords private
+/** @access private */
LzURL.prototype.dupe = function (){
//make this function fast, because it is called by LzBrowser.toAbsoluteURL
//which is called frequently by the loader
Modified: openlaszlo/trunk/WEB-INF/lps/lfc/services/platform/swf/LzBrowser.as
===================================================================
--- openlaszlo/trunk/WEB-INF/lps/lfc/services/platform/swf/LzBrowser.as
2007-11-22 20:48:29 UTC (rev 7356)
+++ openlaszlo/trunk/WEB-INF/lps/lfc/services/platform/swf/LzBrowser.as
2007-11-22 20:49:07 UTC (rev 7357)
@@ -101,10 +101,14 @@
this._dequeueJS();
}
}
+/** @access private */
LzBrowser.__jscallback = null;
+/** @access private */
LzBrowser.__jslocked = false;
+/** @access private */
LzBrowser.__jscallq = [];
+/** @access private */
LzBrowser.__jsready = function () {
//Debug.write('jsready');
LzBrowser.jsready=true;
@@ -118,6 +122,7 @@
LzBrowser._dequeueJS();
}
+/** @access private */
LzBrowser._dequeueJS = function (a) {
this.__jslocked = false;
this.__jscallback = null;
@@ -128,6 +133,7 @@
}
}
+/** @access private */
LzBrowser._jsreset = function () {
this.__jslocked = false;
this.__jscallback = null;
Modified: openlaszlo/trunk/docs/src/xsl/js2doc2dbk/synopsis.xsl
===================================================================
--- openlaszlo/trunk/docs/src/xsl/js2doc2dbk/synopsis.xsl 2007-11-22
20:48:29 UTC (rev 7356)
+++ openlaszlo/trunk/docs/src/xsl/js2doc2dbk/synopsis.xsl 2007-11-22
20:49:07 UTC (rev 7357)
@@ -159,13 +159,28 @@
<xsl:param name="id" select="@id"/>
<xsl:param name="static" select="false()" />
<xsl:param name="prototype" select="false()"/>
- <methodsynopsis language="{$language}">
- <xsl:choose>
+ <methodsynopsis language="{$language}">
+ <xsl:choose>
<xsl:when test="$add-link = true()">
<methodname><link linkend="{$id}"><xsl:value-of
select="@name"/></link></methodname>
</xsl:when>
<xsl:otherwise>
- <methodname><xsl:value-of select="ancestor::property/doc/[EMAIL
PROTECTED]'lzxname']/text"/>.<xsl:value-of select="@name"/></methodname>
+ <methodname>
+ <xsl:choose>
+ <xsl:when test="$static">
+ <!-- For static methods, show the class name -->
+ <xsl:value-of select="../../@name"/>.<xsl:value-of
select="@name"/>
+ </xsl:when>
+ <xsl:when test="ancestor::property/doc/[EMAIL
PROTECTED]'lzxname']/text">
+ <!-- For instance methods, show the name of the class -->
+ <xsl:value-of select="ancestor::property/doc/[EMAIL
PROTECTED]'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:choose>
+ </methodname>
</xsl:otherwise>
</xsl:choose>
<xsl:for-each select="function/parameter">
@@ -235,7 +250,7 @@
</xsl:choose>
<xsl:for-each select="parameter">
<methodparam>
- <parameter>benhiparameterforfunction<xsl:value-of
select="@name"/></parameter>
+ <parameter><xsl:value-of select="@name"/></parameter>
<xsl:if test="@type"><type role="javascript"><xsl:value-of
select="@type"/></type></xsl:if>
</methodparam>
</xsl:for-each>
Modified: openlaszlo/trunk/docs/src/xsl/js2doc2dbk/utilities.xsl
===================================================================
--- openlaszlo/trunk/docs/src/xsl/js2doc2dbk/utilities.xsl 2007-11-22
20:48:29 UTC (rev 7356)
+++ openlaszlo/trunk/docs/src/xsl/js2doc2dbk/utilities.xsl 2007-11-22
20:49:07 UTC (rev 7357)
@@ -57,7 +57,7 @@
</xsl:element>
</xsl:when>
<xsl:otherwise>
- <xsl:text>???</xsl:text>
+ <xsl:text>?lzxtype?</xsl:text>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
@@ -76,7 +76,8 @@
</xsl:element>
</xsl:when>
<xsl:otherwise>
- <xsl:text>?jstype?</xsl:text>
+ <!-- We couldn't find a type for this. -->
+ <xsl:message>No type found for <xsl:value-of
select="@name"/></xsl:message>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
Modified: openlaszlo/trunk/docs/src/xsl/js2doc2dbk.xsl
===================================================================
--- openlaszlo/trunk/docs/src/xsl/js2doc2dbk.xsl 2007-11-22 20:48:29 UTC
(rev 7356)
+++ openlaszlo/trunk/docs/src/xsl/js2doc2dbk.xsl 2007-11-22 20:49:07 UTC
(rev 7357)
@@ -45,9 +45,9 @@
<!-- These params control the presentation of attributes, methods, and
events
using a javascript-oriented syntax and approach. -->
<xsl:param name="show.members.attributes" select="true()" />
- <xsl:param name="show.properties.static" select="false()" />
- <xsl:param name="show.methods.static" select="false()" />
- <xsl:param name="show.events.static" select="true()" />
+ <xsl:param name="show.properties.static" select="true()" />
+ <xsl:param name="show.methods.static" select="true()" />
+ <xsl:param name="show.events.static" select="true()" />
<xsl:param name="show.inherited.attributes" select="true()" />
<xsl:param name="show.setters" select="false()" />
<xsl:param name="show.prototype.methods" select="true()" />
@@ -56,6 +56,7 @@
<xsl:param name="show.init.args" select="false()" />
<xsl:param name="show.lzx.synopsis" select="false()" />
<xsl:param name="show.js.synopsis" select="false()" />
+ <xsl:param name="show.known.subclasses" select="true()" />
<xsl:key name="id" match="*" use="@id"/>
<xsl:key name="unitid" match="*" use="@unitid"/>
@@ -77,7 +78,6 @@
<xsl:if test="count($decls) > 0">
<reference id="{$topicid}" xreflabel="{$topicdesc}">
<title><xsl:value-of select="$subtopic"/></title>
- <!-- [bshine commenting out jgrandy code with unknown purpose
10.07.2007] <xsl:message><xsl:value-of select="concat('found ', count($decls),
' visible items in ', $topicdesc)"/></xsl:message> -->
<xsl:for-each select="$decls">
<xsl:sort select="translate(@id,'_$',' ')"/>
<xsl:apply-templates select="." mode="refentry"/>
@@ -116,6 +116,8 @@
<!-- REFENTRY -->
+ <!-- This is the main template for generating the guts of the reference
information
+ for each class. [bshine 11.21.2007] -->
<xsl:template match="property" mode="refentry">
<xsl:variable name="jsname" select="@name"/>
@@ -244,35 +246,8 @@
<xsl:variable name="events" select="&objectvalue;/[EMAIL
PROTECTED]'__ivars__']/object/property[doc/[EMAIL PROTECTED]'lzxtype']/text =
'event' and &isvisible;]" />
<xsl:variable name="initargs"
select="class/initarg[not(contains(@access, 'private'))]" />
- <!-- Static Properties -->
- <xsl:if test="$show.properties.static">
- <xsl:call-template name="describe-members">
- <xsl:with-param name="members" select="$ovars[not(child::function)
and not(&isevent;)]"/>
- <xsl:with-param name="static" select="true()"/>
- <xsl:with-param name="title" select="'Static Properties'"/>
- <xsl:with-param name="initargs" select="$initargs" />
- <xsl:with-param name="ivars" select="$ivars" />
- <xsl:with-param name="setters" select="$svars" />
- </xsl:call-template>
- </xsl:if>
+
- <!-- Static Methods -->
- <xsl:if test="$show.methods.static">
- <xsl:call-template name="describe-members">
- <xsl:with-param name="members" select="$ovars[child::function]"/>
- <xsl:with-param name="static" select="true()"/>
- <xsl:with-param name="title" select="'Static Methods'"/>
- </xsl:call-template>
- </xsl:if>
-
- <!-- Static Events -->
- <xsl:if test="$show.events.static">
- <xsl:call-template name="describe-members">
- <xsl:with-param name="members" select="[EMAIL
PROTECTED]'LzEvent']"/>
- <xsl:with-param name="static" select="true()"/>
- <xsl:with-param name="title" select="'Static Events'"/>
- </xsl:call-template>
- </xsl:if>
<!-- Initialization Arguments -->
<xsl:if test="$show.init.args">
@@ -302,8 +277,19 @@
<xsl:with-param name="setters" select="$svars" />
</xsl:call-template>
</xsl:if>
+
+ <!-- Static Properties -->
+ <xsl:if test="$show.properties.static">
+ <xsl:call-template name="describe-members">
+ <xsl:with-param name="members" select="$ovars[not(child::function)
and not(&isevent;)]"/>
+ <xsl:with-param name="static" select="true()"/>
+ <xsl:with-param name="title" select="'Class Attributes'"/>
+ <xsl:with-param name="initargs" select="$initargs" />
+ <xsl:with-param name="ivars" select="$ivars" />
+ <xsl:with-param name="setters" select="$svars" />
+ </xsl:call-template>
+ </xsl:if>
-
<!-- Inherited Attributes -->
<xsl:if test="$show.inherited.attributes">
<xsl:call-template name="describe-inherited-attributes">
@@ -332,6 +318,15 @@
</xsl:call-template>
</xsl:if>
+ <!-- Static Methods -->
+ <xsl:if test="$show.methods.static">
+ <xsl:call-template name="describe-members">
+ <xsl:with-param name="members" select="$ovars[child::function]"/>
+ <xsl:with-param name="static" select="true()"/>
+ <xsl:with-param name="title" select="'Class Methods'"/>
+ </xsl:call-template>
+ </xsl:if>
+
<!-- Inherited Methods -->
<xsl:call-template name="describe-inherited-methods">
<xsl:with-param name="class" select="class"></xsl:with-param>
@@ -350,6 +345,15 @@
<xsl:with-param name="class" select="class"></xsl:with-param>
</xsl:call-template>
+ <!-- Static Events -->
+ <xsl:if test="$show.events.static">
+ <xsl:call-template name="describe-members">
+ <xsl:with-param name="members" select="[EMAIL
PROTECTED]'LzEvent']"/>
+ <xsl:with-param name="static" select="true()"/>
+ <xsl:with-param name="title" select="'Class Events'"/>
+ </xsl:call-template>
+ </xsl:if>
+
<!-- Prototype Properties -->
<xsl:if test="$show.prototype.properties">
<xsl:call-template name="describe-members">
@@ -359,6 +363,13 @@
</xsl:if>
</refsect1>
+
+ <xsl:if test="$show.known.subclasses">
+ <refsect1>
+ <xsl:call-template name="describe-known-subclasses" />
+ </refsect1>
+ </xsl:if>
+
</xsl:template>
<xsl:template match="property" mode="detailed-synopsis">
@@ -554,10 +565,6 @@
</xsl:template>
<xsl:template match="initarg|property" mode="describe-member">
- <!-- TO DO: special format for setters (properties with
../object/../[EMAIL PROTECTED]'setters'] structure) -->
- <!-- [bshine 11.2.2007] Now I understand what Jim meant with this
comment! We need to describe
- attributes specially (in some way) if they are listed as "setters" in
the js2doc output.
- I do not yet understand exactly what to do here. -->
<xsl:param name="static"/>
<xsl:param name="describe-js" select="true()"/>
<xsl:param name="describe-lzx" select="true()"/>
@@ -967,7 +974,7 @@
</xsl:call-template>
</refsect1>
</xsl:if>
-
+
<?ignore
<!-- need to turn path into webapp url, not sure how to do that -->
<xsl:variable name="path" select="@path"/>
Modified: openlaszlo/trunk/docs/src/xsl/simple-driver.xsl
===================================================================
--- openlaszlo/trunk/docs/src/xsl/simple-driver.xsl 2007-11-22 20:48:29 UTC
(rev 7356)
+++ openlaszlo/trunk/docs/src/xsl/simple-driver.xsl 2007-11-22 20:49:07 UTC
(rev 7357)
@@ -28,11 +28,12 @@
]>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; version="1.0">
- <xsl:output method="xml"/>
- <!-- simple driver for testing paperpie doctools work -->
+ <xsl:output method="xml" indent="yes"/>
+
<xsl:template match="/">
- <xsl:apply-templates select="/js2doc/property" />
+ <!-- Just pay attention to LzBrowser. We really want good LzBrowser
documentation. -->
+ <xsl:apply-templates select="/js2doc/[EMAIL PROTECTED]'LzBrowser']" />
</xsl:template>
@@ -40,80 +41,26 @@
<!-- /js2doc/[EMAIL PROTECTED]/class/[EMAIL PROTECTED]"setters"] -->
<xsl:template match="property" >
<xsl:variable name="classname" select="@name" />
- <xsl:variable name="setters" select="class/[EMAIL
PROTECTED]'setters']/object/property[not(contains(@access, 'private'))]" />
- <xsl:variable name="instancevariables" select="class/[EMAIL
PROTECTED]'__ivars__']/object/property[not(contains(@access, 'private'))]" />
- <xsl:variable name="initargs"
select="class/initarg[not(contains(@access, 'private'))]" />
- <xsl:variable name="events" select="class/[EMAIL
PROTECTED]'__ivars__']/object/property[doc/[EMAIL PROTECTED]'lzxtype']/text =
'event' and &isvisible;]" />
-
-
- property with name <xsl:value-of select="$classname"/>
-
- events: <xsl:for-each select="$events">
- <xsl:value-of select="@name"/>,
- </xsl:for-each>
+ <xsl:variable name="id" select="@id"/>
+ <xsl:variable name="ovars"
select="&objectvalue;/property[not(&privateslot;) and &isvisible; and
child::function]"/>
+ <xsl:variable name="fvars"
select="&objectvalue;/property[not(&privateslot;) and &isvisible;]"/>
+ <class>
+ <name><xsl:value-of select="$classname"/></name>
+ <id><xsl:value-of select="$id"/></id>
+ <ovars>
+ <xsl:for-each select="$ovars">
+ <name><xsl:value-of select="@name"/></name>
+ </xsl:for-each>
+ </ovars>
+ <fvars>
+ <xsl:for-each select="$fvars[child::function]">
+ <name><xsl:value-of select="@name"/></name>
+ <methodname><xsl:value-of
select="../../@name"/>.<xsl:value-of select="@name"/></methodname>
+ </xsl:for-each>
+ </fvars>
- <!-- things that are both instancevariables and setters are read/write
attributes -->
- <xsl:variable name="setters-names" select="$setters/@name" />
- <xsl:variable name="ivars-names" select="$instancevariables/@name" />
-
- <xsl:variable name="attributes" select="$setters |
$instancevariables"></xsl:variable>
-
-
- attributes: (setters: <xsl:value-of select="count($setters)"/>)
(instancevariables: <xsl:value-of select="count($instancevariables)"/>)
- <xsl:for-each select="$attributes">
- <xsl:sort select="@name" />
- <xsl:variable name="sname" select="@name" />
- <xsl:variable name="issetter" select="count( ancestor::[EMAIL
PROTECTED]'setters'] ) > 0" />
- <xsl:variable name="hassetter" select="count( [EMAIL PROTECTED] )
> 0" />
- <xsl:variable name="isinstancevar" select="count( [EMAIL
PROTECTED]) > 0" />
- <xsl:variable name="isinitarg" select="count( [EMAIL PROTECTED] )
> 0" />
-
- <xsl:if test="$hassetter">
- <xsl:if test="$issetter">
- <xsl:call-template name="unique-attribute">
- <xsl:with-param name="issetter"
select="true()"></xsl:with-param>
- <xsl:with-param name="isinstancevar"
select="$isinstancevar"></xsl:with-param>
- <xsl:with-param name="isinitarg"
select="$isinitarg"></xsl:with-param>
- </xsl:call-template>
- </xsl:if>
- </xsl:if>
- <xsl:if test="not($hassetter)">
- <xsl:call-template name="unique-attribute"></xsl:call-template>
- </xsl:if>
- </xsl:for-each>
-
-
- non-event instancevariables:
- <xsl:for-each select="$instancevariables[not &isevent;]">
- <xsl:sort select="@name" />
- <xsl:value-of select="@name"/>,
- </xsl:for-each>
-
- initargs:
- <xsl:for-each select="$initargs">
- <xsl:sort select="@name" />
- <xsl:value-of select="@name"/>,
- </xsl:for-each>
- </xsl:template>
-
-
- <xsl:template name="unique-attribute">
- <xsl:param name="issetter" select="false()"></xsl:param>
- <xsl:param name="isinstancevar" select="true()"></xsl:param>
- <xsl:param name="isinitarg" select="false()"></xsl:param>
- <xsl:value-of select="@name"/>
-
- <xsl:if test="$isinstancevar and $issetter"> (read/write)</xsl:if>
- <xsl:if test="$isinstancevar and not($issetter)"> (readonly)</xsl:if>
- <xsl:if test="not($isinstancevar) and $issetter"> (virtual) </xsl:if>
- <xsl:if test="not($isinstancevar) and not($issetter)">
(strange)</xsl:if>
- <xsl:if test="@modifiers='final'"> (final)</xsl:if>
- <!--
- <xsl:if test="$isinstancevar"> (instancevariable) </xsl:if>
- <xsl:if test="not($isinstancevar)"> (virtual) </xsl:if>
- -->
- <xsl:if test="$isinitarg"> (initarg)</xsl:if>,
- </xsl:template>
+ </class>
+ </xsl:template>
</xsl:stylesheet>
_______________________________________________
Laszlo-checkins mailing list
[email protected]
http://www.openlaszlo.org/mailman/listinfo/laszlo-checkins
