1

Closed

Bug/inconsistency in ScriptDoc for doc'ing properties

description

I found a weird inconsistency in the way I should doc properties.

If I do like this (like stated on Bertrands blog):
{{
get_enableMouseWheel : function() {
   /// <value type="Boolean">Enables the mouse wheel.</value>
   return this._enableMouseWheel;
}
}}
...the type is correctly set in the .org output, and the <value> tag is stored in the .xml, but <value> is not generating any textual output when I pull that through SandCastle.

If I do this:
{{
get_enableMouseWheel : function() {
   /// <summary type="Boolean">Enables the mouse wheel.</summary>
   return this._enableMouseWheel;
}
}}
I get my code summary, but in the .org file the type is now set to ‘Any’ (SandCastle doesn’t really document the parameters or types yet, but that's another bug that I already have reported to the SandCastle team).

Last way I can think of doing it is using both tags:
{{
get_cursor : function() {
   /// <summary>Gets or sets the map cursor</summary>
   /// <value type="String"/>
   return this.get_element().style.cursor;
}
}}

This works, but its kinda “messy”, and not how I think it’s supposed to be done.

So in this case .xml output reads:
{{
   <member name="P:J:MyClass.UI.BaseNav.cursor">
          <summary>Gets or sets the map cursor name</summary>
          <value/>
   </member>
}}
And the .org:
{{
   <api id="P:J:MyClass.UI.BaseNav.cursor">
          <apidata group="member" subgroup="property" name="cursor"/>
          <memberdata visibility="public"/>
          <proceduredata/>
          <propertydata get="true" set="true"/>
          <returns><type api="T:J:String"/></returns>
          <containers>
                 <library assembly="" module="WebADF"/>
                 <namespace api="N:J:MyClass.UI"/>
                 <type api="T:J:MyClass.UI.BaseNav"/>
          </containers>
   </api>
}}
Closed Feb 13, 2009 at 4:33 AM by

comments