Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 417958

Summary: Document orion.core.astprovider
Product: [ECD] Orion Reporter: John Arthorne <john.arthorne>
Component: DocAssignee: Michael Rennie <Michael_Rennie>
Status: RESOLVED FIXED QA Contact:
Severity: normal    
Priority: P3 CC: mamacdon, Michael_Rennie
Version: 4.0Flags: mamacdon: review+
Target Milestone: 4.0 RC3   
Hardware: PC   
OS: Windows 7   
Whiteboard:
Attachments:
Description Flags
jsdoc updates none

Description John Arthorne CLA 2013-09-24 14:55:57 EDT 
The new service orion.core.astprovider needs real documentation for 4.0, as well as updated to any service affected by this change.
Comment 1 Michael Rennie CLA 2013-10-18 10:35:31 EDT 
I added doc to the wiki: http://wiki.eclipse.org/Orion/Documentation/Developer_Guide/Plugging_into_the_editor#orion.core.astprovider.

I will attach a patch for the JSDoc.
Comment 2 Michael Rennie CLA 2013-10-18 10:40:54 EDT 
Created attachment 236656 [details]
jsdoc updates

Here are some JSDoc updates to ast.js
Comment 3 Mark Macdonald CLA 2013-10-18 15:14:50 EDT 
Thanks for the doc work! 

The one problem here is that @memberof tags need to refer to "fully-qualified" names (like orion.edit.ASTManager or  orion.edit.ASTManager.prototype). With just "ASTManager" JSDoc can't figure out that you're talking about the same symbol.

E.g. this is what I get when running the the file through jsdoc2 (which is, sadly, what Orion currently uses for building our docs)

>> WARNING: Trying to document start as a member of undocumented symbol ASTManager.
>> WARNING: Trying to document stop as a member of undocumented symbol ASTManager.
>> WARNING: Trying to document updated as a member of undocumented symbol ASTManager.
>> WARNING: Trying to document getAST as a member of undocumented symbol ASTManager.

These get silently ignored when building the HTML, as they can't be connected to anything defined with an @name tag.
Comment 4 Michael Rennie CLA 2013-10-21 12:15:33 EDT 
(In reply to Mark Macdonald from comment #3)
> Thanks for the doc work! 
> 
> The one problem here is that @memberof tags need to refer to
> "fully-qualified" names (like orion.edit.ASTManager or 
> orion.edit.ASTManager.prototype). With just "ASTManager" JSDoc can't figure
> out that you're talking about the same symbol.

Thanks for the pointer about the qualified names. I updated the fix and pushed it to github. The pull request is here: 

https://github.com/eclipse/orion.client/pull/27