Re: Generating bullet lists with markdown does not work as expected

[Jeff Williams]

Hello,

I think the issue is that Markdown expects a blank line before the first list item. Try this and see if it works:

/** Here comes a list:

    - Item 1
    - Item 2 
    - Item 3
 */

If you were using asterisks as list bullets, you would also need to include leading asterisks in the comment block; otherwise JSDoc would strip the list bullets:

/**

 * Here comes a list:

 *

 * * Item 1

 * * Item 2

 * * Item 3

 */

Hope that helps.

- Jeff

On Sat, Dec 1, 2012 at 7:56 AM, frontend_dev <kude...@alphanull.de> wrote:

Hi,

seems like I might have found a bug in the markdown plugin. What I want to do is basically the following:

    /** Here comes a List:
        - Item 1
        - Item 2
        - Item 3
    */

Also note that the comments are intended to be in line with the surrounding code. The example above does not work, ignores the list markdown - but other tags work. Does not matter if I change the bullet char to "*" or change intendation. The only thing that - partially - works if I also add an explicit @desciption tag. This works only if there is no other comment above the list, and the list must not have intendation at all:

    /** @description - Item 1
- Item 2
- Item 3
    */

Does not look like this is the intended behavior, right?

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
To view this discussion on the web visit https://groups.google.com/d/msg/jsdoc-users/-/H5TckTXyYd0J.
To post to this group, send email to jsdoc...@googlegroups.com.
To unsubscribe from this group, send email to jsdoc-users...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/jsdoc-users?hl=en.

[frontend_dev]

This works .... a little bit, but still not quite as expected:

    /** Here comes a List:

        - Item 1
        - Item 2
        - Item 3

        Even more Text.
    */

In this case, all the list items and the following paragraph are wrapped in a <pre> tag, no actual <li> tags are generated.

Now, if I change the docs to this:

    /** Here comes a List:

- Item 1
- Item 2
- Item 3

        Even more Text.
    */

I get indeed a bullet list, but now the code intendation looks awful, and in addition, the following line is appended to the list,  with no <br> despite adding two spaces at the end of the line.

OK, let's try to enforce a new paragraph by adding a further empty line:

    /** Here comes a List:

- Item 1
- Item 2
- Item 3

        Even more Text.
    */

Now, the output is even more strange: while I still get a bullet list, the last line of the bullet list is now wrapped in a paragraph, and also the very last line is added to the last  <li> tag, and additionally wrapped with <pre><code>. Does not seem to matter if the last line is intended or not.

So it seems to me that there is something wrong here. Bullet Lists generated by markdown seem to have problems with intendation before the "-" list item (haven't tried prefixing every line with "*", but this is not an option for me). Furthermore, if I add more lines after the list they seem to be formatted incorrectly, and I also ask myself if being forced to insert an empty line before the bulletlist should be really necessary.

[Jeff Williams]

Michael Mathews, the original author of JSDoc, once said that the leading asterisks in comment blocks are "optional, except when they're not." :)

As you've noticed, it's difficult to use Markdown unless you include the leading asterisks in comment blocks. Otherwise you start triggering Markdown features that you may not have wanted. For example, you're getting the <pre> tag because if a line starts with four spaces or one tab, Markdown treats it as a code block.

Since you said that you absolutely cannot use leading asterisks, you could write a JSDoc plugin that strips whitespace at the start of each line in the comment block. However, you'll lose the ability to include a Markdown code block in your comment.

The behavior you're seeing with lists is expected--that's how Markdown normally works. GitHub deals with Markdown line breaks a little differently; it assumes that if you added a hard line break, you meant to start a new paragraph/list/whatever. But JSDoc can't do that, because it's normal for comment blocks to contain line breaks in the middle of a paragraph.

I hope that explanation helps.

- Jeff 

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.

To view this discussion on the web visit https://groups.google.com/d/msg/jsdoc-users/-/5VDIl2dRUzwJ.

[Michael Mathews]

JSDoc does not try to outdent your comments based on the indent of the surrounding code, so if your comment contains material that is sensitive to the indentation then you either need to prefix each line with a star, to show JSDoc where you want the left margin to be, or you need to outdent the entire comment yourself to the real left margin of the file.

Leaving out the leading stars is technically a shortcut because while they expected they are seldom needed. You seem to have happened upon a case where they are needed, so that shortcut isn't available to you it appears.

Michael Mathews
mic...@gmail.com

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.

To view this discussion on the web visit https://groups.google.com/d/msg/jsdoc-users/-/5VDIl2dRUzwJ.

[Michael Mathews]

A rather clever chap I used to work with by the name of Jake Archibald once wrote a plugin for JSDoc 2 that effectively outdented the whole comment by the same amount that the opening line of the comment was at. So

````javascript

       /**

       This is indented 7 spaces

           and this is 10 space

       */

````

would become

````javascript

/**

This is indented 7 spaces

    and this is 10 space

*/

````

It worked in his particular code but as a general solution it is fragile because someone could indent their opening line of JSDoc with 2 tabs, and their second line with 4 spaces, and all different combinations thereof.

Also it kinda falls apart when you write this sort of thing:

````javascript

var x, /**

  ^ That is indented 1 space

       But this is indented 7 spaces

           and this is 10 space

       */

````

But assuming you have enough discipline to always write your comments in a consistent predictable way, and always use exactly _n_ spaces for your indentation, then I agree with Jeff (and Jake) a plugin could do this.

Michael Mathews
mic...@gmail.com

[frontend_dev]

Thanks for the plugin idea! Unfortunately this does not seem to work in my case because:
 

But assuming you have enough discipline to always write your comments in a consistent predictable way,

Yes, I do that.
 

and always use exactly _n_ spaces for your indentation, then I agree with Jeff (and Jake) a plugin could do this.

Unfortunately, I don't use a fixed indentation, but rather follow the indentation of the surrounding code. 

Yeah, I think I have to give up, too bad : (

At least I won't indroduce a LOT of prefixing "*" just to be able to generate some lists.

Anyway, thanks a lot nonetheless for the clarification!

[Michael Mathews]

On 4 Dec 2012, at 18:36, frontend_dev <kude...@alphanull.de> wrote:

Thanks for the plugin idea! Unfortunately this does not seem to work in my case because:
 

But assuming you have enough discipline to always write your comments in a consistent predictable way,

Yes, I do that.
 

and always use exactly _n_ spaces for your indentation, then I agree with Jeff (and Jake) a plugin could do this.

Unfortunately, I don't use a fixed indentation, but rather follow the indentation of the surrounding code. 

By "always use exactly _n_ spaces for your indentation" I mean that for every line of any given comment, from that comment's /** line, to that same comment's **/ line, you always use the same amount of leading whitespace. It sounds like you are probably a practicer of this already, so I wouldn't rule this approach out yet.

Yeah, I think I have to give up, too bad : (

At least I won't indroduce a LOT of prefixing "*" just to be able to generate some lists.

Anyway, thanks a lot nonetheless for the clarification!

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.

To view this discussion on the web visit https://groups.google.com/d/msg/jsdoc-users/-/a754QRm1DHcJ.