Make sure @beta/@public and other tags come after the jsdoc description

[chriswhilar]

Is your feature request related to a problem? Please describe.
Yes. If i put a tag before the tsdoc description like so:

/**
   * @beta
   * Join a meeting.
   * @param meetingLocator - Meeting information.
   * @param options - Call start options.
   * @returns The Call object associated with the call.
   */
    join(meetingLocator: MeetingLocator, options?: JoinCallOptions): Call;

eslint does not give me a warning or error about it. I feel like eslint should enforce for the description to come before any tags

Describe the solution you'd like
I would like for eslint to give me an error when there are tags before the description

Additional context
Not sure if eslint already supports this, but if it does please let me know.

[deyaaeldeen]

Hi @chriswhilar, thanks for reporting this. Could you please tell me more about why this ordering matter?

[chriswhilar]

Hey @deyaaeldeen, so the real issue im having is that if the description does not come first, then msft docs will not show the description in its generated docs so it may just be an issue on how msft is generating the docs.

But it also just seems more natural to enforce all tags to come after description anyways? Or if we can atleast create a eslint option rule to enforce this?

[chriswhilar]

@deyaaeldeen or maybe this could just be a msft docs generation bug?

[deyaaeldeen]

@chriswhilar to give you a background, there are two things at play here. The syntax of our documentation comments and the tool we use for docs generation. For the former, we are half way through to have TSDoc comments everywhere. For the latter, we use TypeDoc which sadly does not yet support TSDoc officially but they plan to in v1.1 TypeStrong/typedoc#1266. So at the moment, TypeDoc does not understand many of TSDoc tags including @beta and most likely will stop once it sees something it does not understand.

For your question, I did some search and could not find any such eslint plugin. I also looked for plugins for TypeDoc for supporting some of the TSDoc tags but only found one for @example https://github.com/ardalanamini/typedoc-plugin-example-tag. However two plugins that caught my eye and maybe useful here are:
https://www.npmjs.com/package/typedoc-plugin-custom-tags
https://www.npmjs.com/package/typedoc-plugin-replace-in-comments

[ramya-rao-a]

Closing this issue as we have no planned next steps here.

We have added a npm script docs for all our packages that are not purely auto generated. This can be used to generate the docs that are closest to what would appear in docs.microsoft.com/javascript/api. This can be used to review the docs before a package is published.