doctool/API pages newlines stripped

[dante]

Newlines are stripped from otherwise "formatted" plain text, which seems "wrong".

For example:

http://api.dojotoolkit.org/jsdoc/dojo/HEAD/dojo.data.api.Read.fetch

is the output for .fetch()'s inline docs:

http://trac.dojotoolkit.org/browser/dojo/trunk/data/api/Read.js#L204

The Read.js inline docs are very extensive and well formatted. It seems like putting pipes in from of each mini "code block" would solve it, but seems excessive? Just looking for how we should make this easier and format properly to encourage better inline doc writing (dojo.data being a great example, go jared!)

I understand why we strip whitespace and newlines, but there has to be some middle ground? is markdown the answer? Does the markdown look inside of summary: and description: tags? (only ever used it in example: tags)

[Neil Roberts]

If it's code, wrap it in a pre or use the pipes. If you simply want a line break, Markdown lets you add two spaces to the end of a line.

[bill]

Moving these to future as per meeting; Neil, when you are ready to work on these you can assign a milestone.

[Neil Roberts]

This is a problem with using a summary as a description. I will create a specific type for keyword args and document that type in its description, with documentation for each property.

[bill]

I think we can call this fixed for 1.8. I got it working so you can format code blocks in the standard markdown way, by indentation. Four spaces in addition to the base-indent level of the text, ex:

// summary:
//         Here's an example:
//
//               var foo = 5;

Of course the vertical bars still work too.

See ​https://github.com/wkeese/js-doc-parse/commit/4e96f6709cc95f7f43525af5157879473e7a068c and ​https://github.com/wkeese/js-doc-parse/commit/c718dfa91b8c479b7e2bf8e4776de483c43ac522.