JsDocDocumentation Provider Intention and Samples

[nametable]

Hi! I've noticed that Langium includes a JsDocDocumentationProvider that can be used for HoverProviders or other use cases. Is the intent that it will eventually become full featured, or that it could just be an example or starter? Right now it provides basic parsing of a JSDoc tag, but it does not cover the parsing of the many variants that may exist (e.g. @param, @returns, etc) .

I have not seen very much documentation relating to the JsDocDocumentationProvider, besides discussion in #1242 . Is there an example/sample of this providers usage, integrating it with a custom grammar? For example, one might want to use the JSDoc @param tag to provide documentation for a function parameter, and then have hover or completion of the use of that parameter show that documentation.

Thanks!

[msujew]

Hey @nametable,

As far as the framework is concerned, the JSDoc functionality is fully-featured. The JsDocDocumentationProvider is simply a service that returns a JSDoc/Markdown based documentation for an arbitrary AST object.

Right now it provides basic parsing of a JSDoc tag, but it does not cover the parsing of the many variants that may exist (e.g. @param, @returns, etc).

What is special about those tags in particular? At least when it comes to the hover behavior, everything seems to work as expected:

For example, one might want to use the JSDoc @param tag to provide documentation for a function parameter, and then have hover or completion of the use of that parameter show that documentation.

I don't think there are examples out there, but this in particular can be accomplished using relatively little code:

const functionParam = ...;
const comment = this.commentProvider.getComment(node);
if (comment && isJSDoc(comment)) {
  const parsedJSDoc = parseJSDoc(comment);
  const paramTags = parsedJSDoc.getTags('param');
  // Find the `@param` tag that starts with the parameter name
  const functionParamTag = paramTags.find(tag => tag.toString().startsWith(functionParam.name + ' '));
  return functionParamTag?.toMarkdown();
}
return undefined;

[nametable]

Thanks for your prompt response @msujew !

What is special about those tags in particular? ...

For example, @params content is made up of a name and then an associated comment. If rendering the entire tag, the content does not need to be parsed out. However, for just using the associated comment, the content of the @param has to be further parsed.

const functionParam = ...;
const comment = this.commentProvider.getComment(node);
if (comment && isJSDoc(comment)) {
  const parsedJSDoc = parseJSDoc(comment);
  const paramTags = parsedJSDoc.getTags('param');
  // Find the `@param` tag that starts with the parameter name
  const functionParamTag = paramTags.find(tag => tag.toString().startsWith(functionParam.name + ' '));
  return functionParamTag?.toMarkdown();
}
return undefined;

Thanks for this example! I may be able to do something similar.