Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

colons make the line h2 #60

Closed
cbou opened this Issue Jul 2, 2012 · 9 comments

Comments

Projects
None yet
4 participants
Contributor

cbou commented Jul 2, 2012

I see this pull request so I think it's a feature not a bug :p

But when I parse this comment:

/**
 * Parse the given comment `str`.
 *
 * The comment object returned contains the following:
 * ...
 */

Then description.body is <h2>The comment object returned contains the following</h2>\n\n<p>...</p>
And without the colon after following it's <p>The comment object returned contains the following<br />...</p>

I think it would be better if it always stays with <p> and if you need <h2> then you can write:

/**
 * Parse the given comment `str`.
 *
 * ## The comment object returned contains the following:
 * ...
 */

This will always returns <h2>The comment object returned contains the following</h2>\n\n<p>...</p> with or without colons.

Otherwise if it should stay as it currently is, then there is a small bug because this comment

/**
 * Parse the given comment `str`.
 *
 *  The comment object returned contains the following
 * ...
 */

will be parsed in <p>The comment object returned contains the following:<br />...</p> even with colon (Notice the two spaces before The comment object...).

Owner

tj commented Jul 3, 2012

I have a lot that look like "Examples: " etc, that if for nothing other than backwards compat I would like to retain that functionality, but other than that I agree. I think we should only transform it to an h2 when it's short though

Contributor

cbou commented Jul 3, 2012

It's a bit obscur, if it's short h2, if not p ...

Owner

tj commented Jul 3, 2012

yup it is but I don't want to go redo docs for hundreds of projects :p

Contributor

cbou commented Jul 3, 2012

I can understand. How to you produce your doc, because dox output is in json. Maybe this feature, "small words with colons becomes h2" could be a feature of the documentation generator and not of javadoc parser (dox) ?

Contributor

ForbesLindesay commented Jul 3, 2012

It's an interesting point, you can ask for dox to give you the markdown directly, and then parse it yourself. I do this myself in my own docs generating library (very much at an alpha stage at the moment) so I can parse the markdown myself and add syntax highlighting at the same time

This method lets you get complete control over the parsing.

Contributor

cbou commented Jul 4, 2012

Thanks ForbesLindesay, I think you mean the raw option ?

I already notice this option. But when I parse Example: and ## Example: there is no diffrence in the output even if with the raw option. Both outputs are:

"description": {
      "full": "Parse the given `str`.\n\n## Examples:\n\n    parse(str)\n    // => \"wahoo\"\n",
      "summary": "Parse the given `str`.",
      "body": "## Examples:\n\n    parse(str)\n    // => \"wahoo\"\n"
    }

Because of this line: .replace(/^([A-Z][\w ]+):$/gm, '## $1')

@cbou cbou closed this Jul 4, 2012

@cbou cbou reopened this Jul 4, 2012

Contributor

cbou commented Jul 4, 2012

Sorry miss click on Close & comment

Contributor

ForbesLindesay commented Jul 4, 2012

ouch, that does seem like a bug to me, I don't think we should do the conversion in raw mode. @visionmedia what are your thoughts?

Owner

tj commented Jul 4, 2012

I dont remember what I did ATM but yeah if it's in .raw that's no good

@Twipped Twipped closed this Mar 18, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment