[OpenLayers-Dev] finally fed up with jsdoc

[Tim Schaub]

Hey-

Glen Stampoultzis wrote:
> How about Natural Docs?
> 
> http://naturaldocs.org/
> 

I'm all in favor of Natural Docs.  I just switched a small project over 
to Natural Docs, and I like it.

Benefits-
Natural Docs comment style is designed to be very readable in the code 
(see example below).  Output HTML docs generated from these comments are 
pretty.  Comment style is flexible, and Natural Docs is easy to customize.

Drawbacks-
Function parameters aren't specified with type.  We can work around this 
by agreeing on a convention for this.  Below is an example of comments 
that do the right thing in Natural Docs (I've used brackets for 
parameter type).  We may need to customize it to get class hierarchy in 
the menu.  The JSForms project uses Natural Docs and has done this.

Natural Docs doesn't have full language support for JavaScript.  I 
actually see this as an advantage.  I think we'll have more luck with 
comment only documentation.

Quick example of something that produces very usable output in Natural 
Docs.  Note that there is all kinds of support for generic topic 
documentation - so pages can have a nice intro etc.

/**
  * Namespace: OpenLayers
  * The place for all things OpenLayers to live.
  */
OpenLayers = {
      /**
       * Property: [String] someProp
       * Description of someProp
       */
       someProp: "default",

      /**
       * Method: doSomething
       * Description of this method goes here
       *
       * Parameters:
       * map [<OpenLayers.Map>] - This map will have something done to it
       * options [Object] - An optional object with some properties
       *
       * Returns:
       * [Object] or maybe [<OpenLayers.Map>] Description of the return
       */
       doSomething: function(map, options) {
           // code here
       }
}

/**
  * Class: OpenLayers.Map
  * Instances of this class are nice maps.
  */
OpenLayers.Map = OpenLayers.Class.create();
OpenLayers.Map.prototype = {
     /**
      * Constructor: OpenLayers.Map
      * Create a new map.
      *
      * Example:
      * > var map = new OpenLayers.Map("mapid")
      *
      * Parameters:
      * id [String] - The id of the element that will contain the map
      * options [Object] - An optional object with some properties
      */
     initialize: function(id, options) {
         // code here
     },

     /**
      * Constant: CLASS_NAME
      */
     CLASS_NAME: "OpenLayers.Map"
}