Opened 15 years ago

Closed 14 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:


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: = function(/* int */ value) {
    // Summary: Returns the square root of a value
    // examples: 
    //   var four =;     // returns 4
    //   var complex =; // returns {real:0, imaginary:4}

Attachments (1)

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

Download all attachments as: .zip

Change History (6)

comment:1 Changed 15 years ago by bill

Owner: changed from neil to Neil Roberts

comment:2 Changed 15 years ago by dylan

Milestone: 0.5

comment:3 Changed 15 years ago by Adam Peller

+1. This ought to be higher priority, IMO

Changed 14 years ago by dante

Attachment: docparser.patch added

comment:4 Changed 14 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 14 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.