[Laszlo-checkins] r9180 - openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc
P T Withington
ptw at pobox.com
Fri May 16 04:01:00 PDT 2008
Approved.
This is a hangover from the olden days when simple assignment (to the
prototype or to a singleton instance) was the way all methods and
attributes got defined. It seems pretty clear to me that you _never_
want to replace some documentation with no documentation, so that
ought to either never happen or the doc tool should issue an error.
Even replacing one bit of doc with another for the same thing ought to
be an error IMO.
When we get everything 'classified', we can probably stop processing
assignments altogether and only look for documentation on declarations.
On 2008-05-15, at 21:59 EDT, dda at openlaszlo.org wrote:
> Author: dda
> Date: 2008-05-15 18:59:27 -0700 (Thu, 15 May 2008)
> New Revision: 9180
>
> Modified:
> openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/
> JS2Doc.java
> openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/
> PropertyReference.java
> Log:
> Change 20080515-dda-n by dda at lester.local on 2008-05-15 19:45:54 EDT
> in /Users/dda/laszlo/src/svn/openlaszlo/trunk-doc
> for http://svn.openlaszlo.org/openlaszlo/trunk
>
> Summary: doc tools process class variable assignments correctly, via
> workaround.
>
> New Features:
>
> Bugs Fixed: LPP-5995
>
> Technical Reviewer: ptw (pending)
> QA Reviewer: (pending)
> Doc Reviewer: max (pending)
>
> Documentation:
>
> Release Notes:
>
> Details:
> Situation is:
> class X {
> /**javadoc**/ static y;
> ...
> X.y = Z;
> }
> The javadoc for y is lost if the assignment happens later.
> If the declaration and initialization happen in a single
> statement (static y = Z)
> the problem will not appear. But the simple code workaround is
> not feasible in all cases.
>
> The basic issue is that the code that processes X.y = Z is
> creating a new X.y node in the
> doc tree, throwing away the old one. This needs to be fixed, but
> in the interest of solving
> this in the short term, a workaround is in place: If a X.y = Z
> is seen, and X is a known
> class, then any processing for this node is skipped.
>
> A current flaw is that X.y = Z must appear (not just y = Z) in
> order for the workaround to recognize it.
>
>
> Tests:
> Rebuilt doc and checked the LzTimerService and LzCursorService
> pages, which did not
> have descriptions for class variables LzTimer and LzCursor
> respectively.
>
>
>
> Modified: openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/
> js2doc/JS2Doc.java
> ===================================================================
> --- openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/
> JS2Doc.java 2008-05-16 01:30:59 UTC (rev 9179)
> +++ openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/
> JS2Doc.java 2008-05-16 01:59:27 UTC (rev 9180)
> @@ -3,7 +3,7 @@
> *
> ****************************************************************************/
>
> /* J_LZ_COPYRIGHT_BEGIN
> *******************************************************
> -* Copyright 2006-2007 Laszlo Systems, Inc. All Rights
> Reserved. *
> +* Copyright 2006-2008 Laszlo Systems, Inc. All Rights
> Reserved. *
> * Use is subject to license
> terms. *
> * J_LZ_COPYRIGHT_END
> *********************************************************/
>
> @@ -259,6 +259,53 @@
> }
> }
>
> + protected boolean isClassName(org.w3c.dom.Element docNode,
> String nm) {
> + org.w3c.dom.Element root = docNode;
> + while (root.getParentNode() != null
> && !"js2doc".equals(root.getNodeName())) {
> + root = (org.w3c.dom.Element)root.getParentNode();
> + }
> + org.w3c.dom.Element prop =
> JS2DocUtils.findFirstChildElementWithAttribute(root, "property",
> "name", nm);
> + if (prop == null) {
> + return false;
> + }
> + org.w3c.dom.Node cl =
> JS2DocUtils.firstChildNodeWithName(prop, "class");
> + return (cl != null);
> + }
> +
> + /**
> + * Determine if we should process an assignment statement.
> + */
> + protected boolean
> shouldProcessSimpleAssignment(org.w3c.dom.Element docNode,
> + SimpleNode
> lhs,
> + SimpleNode
> op,
> + SimpleNode
> rhs) {
> +
> + if (((ASTOperator)op).getOperator() !=
> ParserConstants.ASSIGN) {
> + return false;
> + }
> +
> + // TODO [dda 2008/05/15] workaround for LPP-5995. When
> + // static variable has been already defined and is now
> + // being assigned, the doc attached to the assigment
> + // (which is typically *nothing*) is clobbering all the
> + // doc attached to the static variable declaration. We
> + // recognize and avoid this situation here by preventing
> + // the doc for the assignment from being processed. But
> + // the real solution to this has to do with getting the
> + // property reference for the lhs of the assignment to
> + // resolve properly to the existing static class element.
> + //
> + if (lhs instanceof ASTPropertyIdentifierReference &&
> + lhs.size() == 2) {
> + SimpleNode l = lhs.getChildren()[0];
> + if (l instanceof ASTIdentifier &&
> + isClassName(docNode,
> ((ASTIdentifier)l).getName())) {
> + return false;
> + }
> + }
> + return true;
> + }
> +
> protected void visitTopLevelAssignmentExpression(SimpleNode
> parseNode, org.w3c.dom.Element docNode) {
> // child 1 is the lhs, child 2 is the assignment
> operator, child 3 is the rhs
> checkChildrenLowerBounds(parseNode, 3, 3,
> "visitTopLevelAssignmentExpression");
> @@ -268,10 +315,8 @@
> op = children[1],
> rhs = children[2];
>
> - boolean opIsSimpleAssignment =
> (((ASTOperator)op).getOperator() == ParserConstants.ASSIGN);
> -
> - if (opIsSimpleAssignment) {
> -
> + if (shouldProcessSimpleAssignment(docNode, lhs, op,
> rhs)) {
> +
> try {
> PropertyReference propRef =
> this.resolveBinding(docNode, lhs, this.currentState);
>
> @@ -500,9 +545,7 @@
> SimpleNode op = children[1];
> SimpleNode rhs = children[2];
>
> - boolean opIsSimpleAssignment =
> (((ASTOperator)op).getOperator() == ParserConstants.ASSIGN);
> -
> - if (opIsSimpleAssignment) {
> + if (shouldProcessSimpleAssignment(docNode, lhs, op,
> rhs)) {
> PropertyReference propRef =
> this.resolveBinding(docNode, lhs, this.currentState);
> propRef.redefineProperty(parseNode.getComment());
> if (propRef.hasProperty())
>
> Modified: openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/
> js2doc/PropertyReference.java
> ===================================================================
> --- openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/
> PropertyReference.java 2008-05-16 01:30:59 UTC (rev 9179)
> +++ openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc/
> PropertyReference.java 2008-05-16 01:59:27 UTC (rev 9180)
> @@ -421,5 +421,16 @@
> }
> }
> }
> +
> + public String toString() {
> + StringBuffer sb = new StringBuffer("PropertyReference[");
> + sb.append("owner=" + propertyOwner);
> + sb.append(", name=" + propertyName);
> + sb.append(", state=" + state);
> + sb.append(", cachedProp=" + cachedProperty);
> + sb.append(", cachedValue=" + cachedValue);
> + sb.append("]");
> + return sb.toString();
> + }
>
> }
>
>
> _______________________________________________
> Laszlo-checkins mailing list
> Laszlo-checkins at openlaszlo.org
> http://www.openlaszlo.org/mailman/listinfo/laszlo-checkins
More information about the Laszlo-checkins
mailing list