Opened 14 years ago
Closed 10 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 14 years ago by
comment:2 Changed 14 years ago by
Milestone: | 1.3 → future |
---|
Moving these to future as per meeting; Neil, when you are ready to work on these you can assign a milestone.
comment:3 Changed 13 years ago by
Status: | new → assigned |
---|
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 10 years ago by
Milestone: | future → 1.8 |
---|---|
Owner: | changed from Neil Roberts to bill |
comment:5 Changed 10 years ago by
Resolution: | → fixed |
---|---|
Status: | assigned → closed |
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.
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.