[nebulastudio-discuss] XML descriptions of Nebula classes to provide better wrappers and editor integration

[Bruce Mitchener]

Bruce Mitchener wrote:
> We could use having a much richer data representation for generating 
> richer and higher quality bindings, especially if we go further and want 
> the bindings to contain documentation to fit into their environment, etc.
> 
> A rough shot at the information that I'd like to see:
> 
>    * Class names
>    * Class hierarchy information
>    * Class documentation, from script docs rather than the
>      C++ docs.
>    * Which package/target the class is in (kernel, scene, nmap, etc)
>    * Script methods of the object:
>       * Script method names with Nebula-style proper capitalization so
>         that a wrapper can modify capitalization to match the target
>         language.
>       * Script method documentation
>       * Script method arg information:
>          * Basic type of each arg (as before)
>          * Name of each arg
>          * Semantic type of arg (color, etc.).
>    * Properties of the object:
>       * Name of the property
>       * Documentation on the property
>       * Name of the getter/setter methods (and therefore if it is
>         read-only (no setter)).
>       * Basic type of the property (int, float, vector4, etc)
>       * Semantic type of the property (color, etc). These would be
>         used by NebulaStudio to determine which potential editors
>         to use on the value.
> 
> What else might we want to see?

Leaf brought up the good point that not all setters are simple. Nebula 
has many setters that require further reconstruction of data with a 
begin and end command surrounding adding a list of items, such as 
setting up joints.

A straw man proposal for the above in XML:

<class name="nGfxServer2" parent="nRoot" package="gfx2">
   <documentation>... probably using CDATA ...</documentation>
   <methods>
     <method name="OpenDisplay">
       <documentation> ... </documentation>
       <output>
         <value type="boolean" name="success" />
       </output>
     </method>
     <method name="CloseDisplay" />
     <method name="SaveScreenshot">
       <input>
         <value type="string" name="filename" />
       </input>
     </method>
   </methods>
   <properties>
     <property name="DisplayMode">
       <getter name="GetDisplayMode" />
       <setter name="SetDisplayMode" />
       <valueformat>
         <value type="string" name="WindowTitle" />
         <value type="????" name="type" />  <-- needs thinking about
         <value type="integer" name="XPosition" />
         <value type="integer" name="YPosition" />
         <value type="integer" name="width" />
         <value type="integer" name="height" />
         <value type="boolean" name="vsync" />
       </valueformat>
     </property>
     <property name="FeatureSet">
       <getter name="GetFeatureSet" />
       <valueformat>
         <value type="enumeration">
           <enum name="dx7" />
           <enum name="dx8" />
           <enum name="dx8sb" />
           <enum name="dx9" />
           <enum name="dx9flt" />
           <enum name="invalid" />
         </value>
       </valueformat>
     </property>
     <property name="CursorVisibility">
       <getter name="GetCursorVisibility" />
       <valueformat>
         <value type="enumeration">
            <enum name="none" />
            <enum name="system" />
            <enum name="custom" />
         </value>
       </valueformat>
     </property>
   </properties>
</class>

This leaves out:

   * Leaf's point about begin/add/end type setters.
   * Semantic types of properties.
   * Any hints about editor display.
   * Probably other stuff as well.

  - Bruce