[Laszlo-dev] [Laszlo-checkins] r9180 - openlaszlo/trunk/WEB-INF/lps/server/src/org/openlaszlo/js2doc
P T Withington
ptw at pobox.com
Fri May 16 06:15:05 PDT 2008
You made the right choice. We can either re-open or create a future
improvement for the day when we are 'all classes, all the time'.
On 2008-05-16, at 08:37 EDT, Donald Anderson wrote:
> 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