CODEWITHSUNDEEP
javascriptyuidocumentation-generation
A.M. D.
A.M. D.

Reputation: 928

YUIDoc, best way of documenting 'return that' objects

I'm using YUIDoc for the first time on a new project. I'm creating objects (isolated from one another) that will control creation and tracking of their own shapes, which are later written to the screen.

I have my main object - 'MakeOneOfThese' in the pseudocode below - with a 'ThingMaker' method to return shape definitions.

When I generated the YUIDocs I had a long list of classes at left, and no relationship between them. So I applied @for in the recommended way, but still my leftmost class list did not represent the hierarchy in the classes list or the body of the class docs. The classes list for example read:

My workaround has been to prefix the hierarchy in the @class names with their parent classes. YUIDoc then gives me:

I am keen to know how more experienced YUIDoc users have approached this, and how my solution may be replaced with something more appropriate, or improved upon.

The pseudocode below is ready to be dropped into a file and run through YUIDoc.

Many thanks for any time spent on responses. Anthony

    /**
    The main constructor
    @class MakeOneOfThese 
    @constructor
    @param [options]{Object}
      @param [options.gridSize] {Integer}  The pixel dimensions for the grid
      @default 20

    **/
    function MakeOneOfThese(options) {
      var that= {
          //game properties
          //game methods

        /**
        A shape chooser
        @method ThingMaker
        @constructor
        @param thingType {String}
        @return MakeOneOfThese.ThingMaker.piece {object} an object representing definition information for the
        named shape type
        **/
        ThingMaker: function(thingType) {
            var PieceDefinitions = {
                /**
                A shape definition
                @class MakeOneOfThese.shapeOne
                @return MakeOneOfThese.ThingMaker.piece {object} 
                **/
                shapeOne: function() {
                    var piece = {
                      name: "ShapeOne",
                      signature: {
                         n: [[1],[1,1],[0,1]],
                         e: [[0,1,1],[1,1]], 
                         s: [[1],[1,1],[0,1]],
                         w: [[0,1,1],[1,1]]
                      }
                    }
                    return piece;
                }
                /**
                A shape definition
                @class MakeOneOfThese.shapeTwo
                @return MakeOneOfThese.ThingMaker.piece {object} 
                **/         
                shapeTwo: function() {
                  var piece = {
                    name: "ShapeTwo",
                    signature: {
                       n: [[1],[0,1],[0,1]],
                       e: [[0,1,1],[1,1]], 
                       s: [[1],[0,1],[0,1]],
                       w: [[0,1,1],[0,1]]
                    }
                  }
                  return piece;
                }
          }
      }
      return that;
    }

Upvotes: 2

Views: 909

Answers (2)

JamieJag
JamieJag

Reputation: 1580

Alternatively, you could also try JsDuck, which uses the same tags (almost all) as YUIDoc, and generates documentation that's not only prettier, but also maintains the class hierarchy

Upvotes: 1

John Lindal
John Lindal

Reputation: 628

Instead of @class MakeOneOfThese.shapeTwo, you can us

@namespace MakeOneOfThese

@class shapeTwo

Upvotes: 0

Related Questions