getDoclets() util ignores content when on a new line

[levithomason]

Use Case

When writing @examples, it is common to have content on the line following the tag (as in the docs).

/**
 * @example
 * Some instructions.
 */

Issue
getDoclets() does not correctly capture doclet contents if they are on a new line following the tag.

Expected: {"example": "Some instructions."}
Actual: {"example": true}

Edge Case
If text content is placed on the same line as the @example tag, then the entire example content is captured:

/**
 * @example foo
 * Some instructions.
 */

Output {"example": "foo\nSome instructions."}

---

Multiple Examples

It is very common to have multiple examples in one docblock. Since keys must be unique, the current util only permits a single example in the parsed docblock object.

Suggestion
The example key may be better suited as an array in the parsed object:

/**
 * @example
 * Some instructions.
 * @example
 * Some other instructions.
 */

Output

{
  "examples": [
    "Some instructions.",
    "Some other instructions."
  ]
}

Let me know if I should file a separate issue for this.

EDIT
Originally submitted before completion.

[levithomason]

If it is of any interest, there are some jsdoc parsers out in the wild that may save duplication of effort.

Eslint built doctrine for the valid-jsdoc and require-jsdoc rules. I tried the demo with the multiple example above and got:

{
    "description": "",
    "tags": [
        {
            "title": "example",
            "description": "Some instructions."
        },
        {
            "title": "example",
            "description": "Some other instructions."
        }
    ]
}

There are others as well, though in my estimation doctrine is the best and most maintained. Cheers!

[fkling]

Where/when are you using getDoclets? react-docgen itself doesn't actually try to parse the doclets because there are other tools out there that do a better job (as you noticed :) ).

I think getDoclets exists only for legacy reasons... you are free to use any other tool that exists if getDoclets doesn't work for you.

I don't see why react-docgen should depend on an external tool if it doesn't use it itself though...

[levithomason]

When/where...

A gulp plugin.

I don't see why react-docgen should depend on an external tool...

I originally followed this comment on #5.

Thanks for clarifying the purpose of getDoclets. Hindsight from here is clear, I'll use something like doctrine instead.

[fkling]

Ah I see, fair enough :)