Opened 13 years ago

Closed 12 years ago

#1473 closed enhancement (fixed)

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

Reported by: skinner Owned by: Neil Roberts
Priority: lowest Milestone: 1.0
Component: Doc parser Version: 0.3
Keywords: Cc: skinner@…
Blocked By: Blocking:

Description

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}
}

Attachments (1)

docparser.patch (15.6 KB) - added by dante 12 years ago.

Download all attachments as: .zip

Change History (6)

comment:1 Changed 13 years ago by bill

Owner: changed from neil to Neil Roberts

comment:2 Changed 13 years ago by dylan

Milestone: 0.5

comment:3 Changed 13 years ago by Adam Peller

+1. This ought to be higher priority, IMO

Changed 12 years ago by dante

Attachment: docparser.patch added

comment:4 Changed 12 years ago by 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?)

comment:5 Changed 12 years ago by dante

Resolution: fixed
Status: newclosed

(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

Note: See TracTickets for help on using tickets.