Opened 14 years ago
Closed 13 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: | [email protected]… | |
Blocked By: | Blocking: |
Description
I've been reading the Code Documentation wiki page:
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)
Change History (6)
comment:1 Changed 14 years ago by
Owner: | changed from neil to Neil Roberts |
---|
comment:2 Changed 14 years ago by
Milestone: | → 0.5 |
---|
comment:3 Changed 14 years ago by
Changed 13 years ago by
Attachment: | docparser.patch added |
---|
comment:4 Changed 13 years ago by
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?)
+1. This ought to be higher priority, IMO