Autodesk Creative Platform Core Version 1.19.0
A broad and deep collection of 2D and 3D capabilities.

How To Document Your Creative Platform Library

The documentation system uses industry standard YUIDoc, along with a few proprietary extensions. What's even better is that developers can take full advantage of this system when developing your libraries, to help document contributions in manner consistent with the Creative Platform. Creative Platform Libraries are documented with 4 basic high-level concepts, to help developers get a high-level view of the library:
  • Topics

    Articles that provide a conceptual overviews or background information that may be needed to understand some of the technical aspects. These can also be used to provide getting started guides, tutorials, etc.

  • Statics

    Objects that are more often than not singletons, and accessed statically and do not require instantiation.

  • Classes

    Classes that are created directly by the client, or accessed via properties and methods of other objects.

  • Enums

    Enumerations that the library provides.

Comment Tags

The following are the YUIDoc tags that are currently supported in the HTML presentation for documentation. Other tags from YUIDocs can be used but are not presented at this time. In addition there are several additional tags that are proprietary with special meaning, as indicated below:

Symbol Tags

When documenting property or argument types, developers can provide direct links to symbols in these scenarios using braces { ... } with the symbol identifier contained within them. These symbol tags are also processed in descriptions of classes, topics and library overviews.
  • Classes, Enums, or Methods within library:
    /**
    @param {ClassName}
    @see {ClassName#memberName}
    */
  • Classes, Enums, or Methods within referenced library:
    /**
    @param {LibraryAlias.ClassName}
    @see {LibraryAlias.ClassName#memberName}
    */
  • JavaScript Objects (See Global Objects):
    /**
    @param {JavaScriptObjectName}
    */
  • An Array of Classes:
    /**
    @param {Array[Number]}
    @param {Array[Object|ClassName]}
    */
  • Maps of Objects:
    /**
    @param {Object[String, Number]}
    @param {Object[Number, LibraryAlias.ClassName]}
    */
  • Variable number of arguments:
    /**
    @param {Function(String*)}
    @param {Number*}
    */
  • The set of JavaScript objects that are internally recognized and get links automatically provided are listed below (case sensitive):
    • {Array}
    • {ArrayBuffer}
    • {Boolean}
    • {DataView}
    • {Date}
    • {decodeURI}
    • {decodeURIComponent}
    • {encodeURI}
    • {encodeURIComponent}
    • {Error}
    • {eval}
    • {EvalError}
    • {Float32Array}
    • {Float64Array}
    • {Function}
    • {HTMLElement}
    • {Infinity}
    • {Int16Array}
    • {Int32Array}
    • {Int8Array}
    • {isFinite}
    • {isNaN}
    • {JSON}
    • {Math}
    • {NaN}
    • {Number}
    • {Object}
    • {parseFloat}
    • {parseInt}
    • {Promise}
    • {RangeError}
    • {ReferenceError}
    • {RegExp}
    • {String}
    • {SyntaxError}
    • {TypeError}
    • {Uint16Array}
    • {Uint32Array}
    • {Uint8Array}
    • {Uint8ClampedArray}
    • {undefined}
    • {Window}
    • {$.Deferred}

    Additional Formatting

    In addition to the tags above which can be used to link directly to types, there are some additional tags that are processed when outputting text from a @topic block, library introduction or class description. All of these are case-sensitive with no extra spacing allowed, to ensure optimal performance while parsing:
    • HTML

      Full HTML is allowed, so just about anything is possible.

    • Images

      Inserting images, by referring to the name of resource using the built-in {@ResourceUrl:} tag

      <img src="{@ResourceUrl:illustration.jpg}" style="width: 50px; height: 100px;"/>

    • Equations

      Inserting equations generated by LaTeX editors such as CODECOGS, by adding the image as a resource and referring to it using the {@ResourceUrl} tag

    • Code Examples

      Inserting code snippets via Prettify. Please refer to the Prettify documentation for to specify the language (i.e. JavaScript, HTML, etc.).

      <pre class="prettyprint">
      // Code Snippets Go Here
      var foo = 1.0;
      var bar = 2.0;
      var zoo = foo / bar;
      </pre>
      
    • Advanced

      Disabling or Re-enabling Formatting

      /**
      {@Tokens:Off}
      {Mesh3D} // Will print as plain text, rather than a link to Mesh3D
      {@Tokens:On}
      */

    Example Documentation Templates

    The following templates are provided as conveniences for developers to help them get started documenting their code. The example templates below can be embellished with additional tags as well, but the templates below are considered the best practice for the bare minimum.
    • Class Template
      /**
      A description of the class goes here.  
      This can be HTML and Markdown.
      @since 1.0
      @class ClassName
      **/
      
    • Return Object With Properties
      /**
      This method returns an object with several properties.
      @method overlappingCurves
      @return {Array[Object]} Array of objects with these properties:
      @return {Point2D} result.intersection Position of overlap.
      @return {Curve2D} result.firstCurve The first curve. 
      @return {Curve2D} result.secondCurve The second curve.
      **/
      
    • Experimental Template
      /**
      Indicates a class, static, interface, enum, method or property is
      experimental and not intended for use yet.
      @since 1.0
      @method methodName 
      @experimental
      **/
      
    • Markdown Template
      /**
      Using the markdown tag allows the author to:
      # Selectively choose which descriptions get processed as markdown
      # Avoid unintended consequences on other blocks which may be HTML
      # Take advantage of one of the most popular forms of documentation
      @since 1.0
      @method methodName 
      @markdown
      **/
      
    • Topic Template
      /**
      A description of the topic goes here.  
      This can be HTML and Markdown.
      @since 1.0
      @topic Topic Name
      **/
      
    • Open Source / Attribution Template
      /**
      A description of the open source library and why it's 
      included can be listed here.  If the library is used
      as-is with no modifications, then @source identifies
      the filename included without modifications.  If the 
      library has been modified, then use @derivative 
      rather than @source.
      @opensource Library r1.2.3
      @websiteurl https://library.com
      @downloadurl https://library.com/downloads/r1.2.3.min.js
      @licenseurl https://library.com/downloads/LICENSE
      @licensetext <Full text...
      ...of the license>
      @source r1.2.3.min.js
      @symbols TopLevelSymbols, AnotherTopLevelSymbol
      **/
      
    • Promise Template
      /**
      A method or property that returns a Promise or 
      $.Deferred object can document the callback parameters 
      for the Resolved, Rejected and Progress callbacks.  The 
      type supplied after the promise tag is optional, but
      provides additional info to consumers about the exact 
      type of object returned.  The Resolved, Rejected and 
      Progress tags are all optional.
      @method someMethod
      @promise $.Deferred
      @resolved Description for resolved callback.
      @param {Object} result The resulting object.
      @rejected Description for rejected callback.
      @param {Error} err Descriptive error info.
      @progress Description for progress callback.
      @param {Number} percent The percent complete.
      @param {String} status Status information.
      **/
      
    • Interface Template
      /**
      A description of the interface goes here.
      This can be HTML and Markdown.
      @interface ShapeInterface
      **/
      
      	/**
      	This is a member on the interface.
      	@method size
      	@return {Box3D}
      	**/
      
      /**
      This is an example of a class that implements it.
      @class Sphere
      **/
      
      	/**
      	The description, return and parameters are 
      	automatically taken from inheritted member.
      	@method size
      	@implements ShapeInterface
      	**/
      
    • Static Template
      /**
      A description of the static class goes here.  
      This can be HTML and Markdown.
      @since 1.0
      @class StaticName
      @static
      **/
      
    • Version Template
      /**
      Allows the library developer to add notes about 
      a particular version for a user.  The versions 
      are sorted based on the released attribute which 
      is an ISO formatted time, and should always be 
      included.
      @version 1.20
      @released 2014-01-01T00:00:00Z
      **/
      
    • JSON Template
      /**
      A description of the JSON object goes here.
      This can be HTML and Markdown.
      @since 1.0
      @json IdentifierJSON
      **/
      
    • Enum Template
      /**
      A description of the enum goes here.  
      This can be HTML and Markdown.
      @since 1.0
      @static
      @enum EnumName
      **/
      
    • Suppress Template
      /**
      A derived class can suppress members that are
      irrelevant using the suppress keyword with a 
      @extend BaseClass
      @class DerivedClass
      @suppress memberOne, memberTwo, memberThree
      **/
      
    • Unlisted Template
      /**
      An unlisted topic, class, static or enum will not
      appear listed on the index page
      @since 1.0
      @topic Unlisted Topic Name
      @unlisted
      **/
      

    Documentation Style Tips

    To have really great consistent documentation, our internal developers try to follow the basic principles:
    • Topics

      For larger libraries that have lots of interdependencies, the documentation added to individual items often fails to illustrate the larger context. Using @topic tags to provide separate articles to users that provide a top-down introduction can be extremely helpful to helping users get started.

    • Headings

      Use <h1>, <h2> and <h3> to organize content in topics. The Return To Library Index links are automatically added to all <h1> tags.

    • Descriptions

      Provide meaningful descriptions for everything that engage and entertain the reader!

    • Example Code

      Provide coding examples using <pre class="prettyprint">...</pre> with good comments. When possible provide completely working samples that can be copied & pasted.

    • Stylize Code References

      When referring to code in text, use <code> to make it clear to the reader that code is being referred to.

    • Links

      When referring to a class, method, static, etc, provide a direct hyperlink to the symbol using Symbol Tags for convenience to the reader.

    • Keywords

      Emphasizing keywords and terminology using the <em> tag to make it clear to the reader this is important or unique to what's being discussed.

    • Illustrations

      Try to include illustrations and images using the {@ResourceUrl} tag whenever possible. Pictures are worth 1,000 words.

    • UI Elements

      When referring to a User Interface element, you can create elements Like This by using the ui-element class:

      <span class="ui-element">Like This</span>

    • See Also

      It can be extremely helpful to document where objects can be obtained from when they're non-instantiable, or where they are used. We encourage liberal use of @see tags.

    • Point Of View

      Try to avoid the trap of First and Second Person point of view in documentation. It's incredibly easy to use 'you' or 'I', however alternatives should always be used.

    • Key Terminology

      Terms such as the Autodesk Creative Platform, Shape Generators and Library should be used consistently and correctly. Terminology such as Shape Script, has been retired because the term was overloaded with multiple meanings representing 1) An underlying technology, 2) A file a user edited and 3) An intelligent kind of shape in Tinkercad.