lloyd / docstract Goto Github PK

should be able to specify custom tags and callbacks to process their textual arguments.

where this may be a blob of text and it's up to the renderer to decide how to link/display it. Multiple @see fields can occur in a documentation block, so JSON representation should be an array. Example:

@see #module/menu/MenuItem
@seealso #module/path/dirname

NOTE: again, I'm don't think it makes any sense to impose restrictions on the value of the @see
tag, that's up to mr renderer. In this example it's a hashtag that's meaningful in some renderer I'm familiar with (chromeless).

Re-using RuntimeError is silly.

Hi,

I currently worked out a specification to make results of DocTools interoperable. This is completely new and the spec is just one day old. The idea of this spec is, that doctools deliver their output in this interoperable format and generating the output can be done by others, that don't want to work on the parsing part.

The benefits would be:

• End users can choose whatever doctool they want and which output generator they want.
• Doctool developers can focus on parsing the code, generate a standardised output and leave the output generation to the end users (doesn't that sound like less work for you?)

My blog post with my motivation for creating this: http://gos.si/blog/docspec-as-interoperable-file-format-between-doctools

As I said the DocSpec is not older than a day, you are invited to join here. Also if you feel like this idea suits your doctool, feel free to jump over to express your interesst in participating as an implementor.

The DocSpec is on github, ready to fork: https://github.com/gossi/docspec

Thank you
gossi

Docstract should deal with some syntax to indicate optional arguments and populate a flag in the output json. Suggestion? Use brackets:

@param {string} [foo]

output:

{
    "name": "foo",
    "type": "string",
    "optional": true
}

It's a worthwhile though experiment to determine how much work would be required to gain near 100% support for all jsdoc tags..

This is the convention in jsdoc.

currently it seems that we simply overwrite the constructor if another appears:

https://bugzilla.mozilla.org/show_bug.cgi?id=636319#c13

The block type guessing heuristics are too simple and stupid right now. I'm thinking that we should instead have a list of guessing functions. Inputs to the function are:

• The information we've parsed out of the content block (many tags may not be present in all types of documentation blocks)
• The first non-whitespace line of code after the content block

The function should then either return the guessed name and type of the docblock, or fail. This method will ultimately allow client code to specify its own heuristics to append to the list.

For each documented atom it would be nice if line numbers were included in the JSON. This would allow renderers to do fancier linking and inline code display.

Currently there's no way to have a complex argument like an object. Here's some example source code where this would be useful (currently inline markdown is used to document complex args):

https://github.com/mozilla/chromeless/blob/e387b27/packages/addon-kit/lib/request.js#L122-161

Syntax may look something like this:

/**
 * @function open
 * Opens a new tab.
 *
 * @param options {object
 *   @prop [url] {string}
 *   String URL to be opened in the new tab.
 * }
 * Options for the new tab.
 */