[Laszlo-dev] [Laszlo-checkins] r9180 - openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc
Donald Anderson
dda at ddanderson.com
Fri May 16 05:37:18 PDT 2008
Yes - I realized too late that probably a better (internal) workaround
would be to check if
there was no doc associated with the incoming node and punt in that
case.
The current setup works with non-static vars, successfully merging
anything I think.
I also agree that we can get rid of docs attached to assignments -
probably the eventual
final resolution of this, but I realized that there may be still some
of those floating
around, so I made the patch as narrow as I could.
- Don
On May 16, 2008, at 7:01 AM, P T Withington wrote:
> 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
>
--
Don Anderson
Java/C/C++, Berkeley DB, systems consultant
voice: 617-547-7881
email: dda at ddanderson.com
www: http://www.ddanderson.com
More information about the Laszlo-dev
mailing list