544533 - Adobe ASDoc edits are needed for some flash.sampler API content

Status: VERIFIED FIXED

(Tamarin Graveyard :: Virtual Machine, defect, P2)

Description

[djacowit]

User-Agent:       Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.1.7) Gecko/20091221 Firefox/3.5.7
Build Identifier: 

Sampler.as  content: NewObjectSample.size needs documentation for Adobe ASDoc output.

    	/**
    	 * The NewObjectSample object size. If the object has been garbage collected, this property is
    	 * undefined and a corresponding DeleteObjectSample exists. For Flash Player debugger version only.
         * @playerversion Flash 9.0.115.0
         * @langversion 3.0     
         * @keyword NewObjectSample, NewObjectSample.size, size 
         * @see flash.sampler.DeleteObjectSample         
    	 */
        public native function get size() : Number;
        
2)
flash.sampler package level method getLexicalScopes() needs grammar fix in documentaton for Adobe ASDoc output:

is:		        * Expose the lexical scope of a Function so that activation objects and with objects and all
should be:      * Expose the lexical scope of a Function so that activation objects and all

Reproducible: Always

Comment 1

[Trevor Baker]

Please generate and attach a patch for the changes.  Thanks.

Comment 2

[Brent Baker]

Attachment: documentation patch

Dan can you review this patch, I do not think that Dave Jacowitz has review rights.

Comment 3

[Dan Schaffer]

Comment on attachment 425829 [details] [diff] [review]
documentation patch

confirmed the patch matches Dave's changes.

Comment 4

[Brent Baker]

Comment on attachment 425829 [details] [diff] [review]
documentation patch

Pushed patch:
tr-argo -> 3683:e52cc201111f
tr -> 3782:e52cc201111f

Comment 5

[Mike Morearty]

I think the change made to the documentation for getLexicalScopes() may have been incorrect -- Tommy, can you weigh in on this:

> 2)
> flash.sampler package level method getLexicalScopes() needs grammar fix in
> documentaton for Adobe ASDoc output:
> 
> is:                * Expose the lexical scope of a Function so that activation
> objects and with objects and all
> should be:      * Expose the lexical scope of a Function so that activation
> objects and all

I agree that the original needs a change, but the point of the original, I'm pretty sure, was to indicate that objects that were the target of the ActionScript "with" keyword will be returned.  I think the fix would be to add double-quotes around the word "with":

> * Expose the lexical scope of a Function so that activation
> objects and "with" objects and all

Comment 6

[djacowit]

ah, I see. I brought up the bug because a localization vendor caught it and couldn't translate it. Given what Mike says, I think it should probably be:

...so that activation objects and objects that are the target of the "with" keyword are seen by the profiler...

Comment 7

[Mike Morearty]

Yes, that wording sounds good to me.  Dave, you want to reopen the bug?

Comment 8

[djacowit]

reopened.

Comment 9

[Trevor Baker]

status?

Comment 10

[Brent Baker]

Attachment: fix getLexicalScopes() asdoc

Comment 11

[Brent Baker]

Attachment: fix getLexicalScopes() asdoc

clean up the previous patch

Comment 12

[Mike Morearty]

Comment on attachment 429522 [details] [diff] [review]
 fix getLexicalScopes() asdoc 

This patch restores the reference to objects that are the target of the "with" keyword, but removes the reference to "all captured scope objects," which I think should still be there.

The missing phrase ("all captured scope objects") is, I believe, a reference to the objects on the scope chain; Tommy would know for sure.

As a more minor point, as long as you are in there modifying this, don't we typically use the third person in asdoc?  E.g. "Exposes" instead of "Expose".

Comment 13

[Brent Baker]

(In reply to comment #12)
> (From update of attachment 429522 [details] [diff] [review])

This was the patch that Dave Jacowitz had already submitted into P4... will ping him with this bug to comment on.

CL#643234

Detailed Description: updating phrasing for getLexicalScopes() to sync up with proposed text in bugzilla bug 544533 so we can get it into next week's localization handoff for the language reference.

Comment 14

[Brent Baker]

-----Original Message-----
From: Dave Jacowitz 
Sent: Tuesday, March 02, 2010 11:06 AM
To: Brent Baker
Subject: RE: [Bug 544533] Adobe ASDoc edits are needed for some flash.sampler API content

I think we're waiting on Tommy for review. I will go with whatever is decided. I just needed to change it so some Localization vendors could piece together a sentence. But once it is changed, they'll alter it as needed.

I'm also fine with changing "Expose" to "Exposes". But as it was before, the Localization vendors were stuck.

Comment 15

[Trevor Baker]

Comment on attachment 425829 [details] [diff] [review]
documentation patch

please push

Comment 16

[Brent Baker]

Attachment: v2. fix getLexicalScopes() asdoc

Comment 17

[Tommy Reilly]

Comment on attachment 431105 [details] [diff] [review]
v2. fix getLexicalScopes() asdoc 

A with object is a captured scope object.  To me this reads like "all developers and C++ developers...".   A real improvement would be to describe the complete set of scope objects but this isn't the place for that.

Comment 18

[Tommy Reilly]

Comment on attachment 431105 [details] [diff] [review]
v2. fix getLexicalScopes() asdoc 

Better would be:

Exposes the lexical scope of a Function so that captured scope  objects (including activation objects and with scopes) are seen by the profiler as being retained by the Function instance.

Comment 19

[Brent Baker]

Attachment: v3. fix getLexicalScopes() asdoc

patch based on Tommy's comment #18

Comment 20

[Brent Baker]

Comment on attachment 431408 [details] [diff] [review]
v3. fix getLexicalScopes() asdoc 

pushed patch:
tr-argo -> 3779:8fb2ba512154

Comment 21

[Brent Baker]

patch merged into tamarin-redux: 3968:8fb2ba512154