jsdoc: @tag strips doc.description, keeps doc.content

[dherges]

I have a file with a @tag at the beginning of the file.

The tag def for @tag is straight forward.

Now, after running processors of jsdoc packages (parse-tags, extract-tags) doc.content still has the original, unmodified tag, while doc.description is empty. When moving @tag to the bottom of the file, all but that last line w/ @tag are kept in doc.description.

Here's the nunjucks rendering template:

{# content works! #}
{{ doc.content | marked }}
<hr><hr><hr>
{# description is stripped because of @title tag! #}
{{ doc.description | marked }}

Now, is this intended behaviour?

[dherges]

Now, what is also strange, when using the @title as demonstrated in the previous post. The doc loooks like:

{
  content: '@title foobar!\n\n# Things to keep in mind\n\n> Hello again\n\n\n```ts\n// Here we can write more code doc\nconst foo = new Foo();\nfoo.foo(\'bar\');\n```\n\n### Great!\n\nIt works!\n\n{@inline foo bar}\n\n',
  fileName: 'test.md',
  title: 'foobar!\n\n# Things to keep in mind\n\n> Hello again\n\n\n```ts\n// Here we can write more code doc\nconst foo = new Foo();\nfoo.foo(\'bar\');\n```\n\n### Great!\n\nIt works!\n\n{@inline foo bar}'
}

So the title property has the whole content of the markdown file. I supposed it should only be "foobar!".

It looks like – to me – in the extract-tags.js, tag is parsed, then the lineNumber is increased one time too much, and then it skips over the following lines until the end of document.

Can someone explain how custom @tag definitions are supposed to work? ❓ I am really confused... 😕

[petebacondarwin]

Remember that jsdoc tags are not single line. We capture all the following text until the next tag. So this is working as expected. If you want to have description following the title tag then you would do:

@title Some tile
@description
The rest of this is description