Opened 11 years ago

Closed 7 years ago

#6986 closed defect (fixed)

doctool/API pages newlines stripped

Reported by: dante Owned by: bill
Priority: high Milestone: 1.8
Component: Doc parser Version: 1.1.1
Keywords: Cc:
Blocked By: Blocking:

Description

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)

Change History (5)

comment:1 Changed 11 years ago by 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.

comment:2 Changed 11 years ago by bill

Milestone: 1.3future

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

comment:3 Changed 10 years ago by Neil Roberts

Status: newassigned

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.

comment:4 Changed 7 years ago by bill

Milestone: future1.8
Owner: changed from Neil Roberts to bill

comment:5 Changed 7 years ago by bill

Resolution: fixed
Status: assignedclosed

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.

Note: See TracTickets for help on using tickets.