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:


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

For example:

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

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 ( 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 and

Note: See TracTickets for help on using tickets.