Enhancement for Example tag

[GoogleCodeExporter]

I needed examples to contain a number and a caption. For example:

Example 1 This is an example of blah...

The @example tag simply wrote out the contents after it. I modified the 
DocTag.js prototype parse function and added a function 
called 'nibbleCaption'. The syntax for the example tag can be as is 
currently implemented or the user can add the following:

@example [Example_1] {This is an example of blah...}

The value in the brackets is converted to the property name (and I change 
underscores to spaces though this probably isn't necessary and should just 
accept spaces), and the the text within the curly braces is set to the new 
property 'caption'.

Because name needs to grab the text within brackets, I needed to skip the 
call to nibbleType which was easily diverted through a simple if statement.

I've attached the changed DocTag.js for your consideration.

-Steve
slarsen@centricitysystems.com

 to read as follows:

JSDOC.DocTag.prototype.parse = function(src) {
    if (typeof src != "string") throw "src must be a string not "+
(typeof src);

    try {
        src = this.nibbleTitle(src);
        if (JSDOC.PluginManager) {
            JSDOC.PluginManager.run("onDocTagSynonym", this);
        }
        // S.Larsen - added functionality for example to have type 
and name
        // @example {My Example description} Example source code

        if (this.title != "example") {
          src = this.nibbleType(src);
        // only some tags are allowed to have names.
        if (this.title == "param" || this.title == "property" || 
this.title == "config") { // @config is deprecated
            src = this.nibbleName(src);
        }
        } else {
          // reverse Example_1 {my caption description}
          src = this.nibbleName(src);
          // added ability to get a caption
          src = this.nibbleCaption(src);
        }

    }

Original issue reported on code.google.com by slar...@centricitysystems.com on 21 Aug 2009 at 9:03

Attachments:

• DocTag.js

[GoogleCodeExporter]

Original comment by micmath on 12 Sep 2009 at 6:26

• Added labels: Type-Enhancement

[GoogleCodeExporter]

I think this is useful but your implementation is in the wrong place, as this 
feature, in my estimation, is a better job for the View Layer. So I'd suggest 
this be implemented in a custom template instead. In your publish.js you could 
iterate over an examples and apply any special formatting you wished, for 
example.

Original comment by micmath on 3 Jul 2010 at 8:14

• Changed state: WontFix