API doc generator -- permit 'examples' as well as 'summary' and 'description'

[skinner]

I've been reading the Code Documentation wiki page:

​http://dojo.jot.com/Code%20Documentation

That page says that in the comment block for a function, the API doc generator will look for a 'summary' section and a 'description' section.

Often a few simple examples are far more useful than a detailed description. It'd be great if the doc generator recognized 'example' and 'examples' as keywords in the example block. For example:

dojo.foo.squareRoot = function(/* int */ value) {
    // Summary: Returns the square root of a value
    // examples: 
    //   var four = dojo.foo.squareRoot(16);     // returns 4
    //   var complex = dojo.foo.squareRoot(-16); // returns {real:0, imaginary:4}
}

[Adam Peller]

+1. This ought to be higher priority, IMO

[dante]

patch attached to this ticket fixes style guide in one docparser php class file, and fixes this ticket, as well as #1474 by making some other keywords accessible, and makes adding other keywords almost a no brainer. added keywords are "examples" and "exceptions" ...

tested, parser is picking up test examples: strings in object declarations,(should be do example: too/instead?)

[dante]

(In [10650]) fixes #1474 - you can put exceptions: (comment) inline doc, and the tool picks it up fixes #1473 - allows examples: (comment) to be picked up by parser refs #4591 - lots of style cleanups to parser php files