Skip to content

API docs: LSIF: protocol: add all the tags

Administrator requested to merge sg/apidocs-all-the-tags into sg/lsif-apidocs-identifiers

Created by: slimsag

@felixfbecker brought up a small request: to add symbol type icons next to e.g. functions, and any other type of symbol found in API docs. This got me thinking about how to implement this.

For one aspect, we don't have this data today. Since API docs are emitted as dumb hierarchial e.g. sections of markdown documentation, there isn't any indicator of what is actually in those sections of documentation - that is, we don't know what kind of symbol the documentation is describing or even if it is a symbol.

We could just expose an optional SymbolKind, as workspace/symbols etc. do - but it would be a little odd as it would be the only part of the documentation extension to LSIF which is symbol-specific, so far it is completely agnostic from the types of content being documented.

Instead, I've opted to extend the tagging system (which thus far was only used to distinguish between public/private documentation) with all the same types of SymbolKind (so they can be easily mapped if desired). I've also added tags for some other useful things:

  • Test functions
  • Example functions/code
  • License information
  • Owner information
  • Package registry information

There are two other benefits to this form of tagging:

  1. There can be multiple tags for a given piece of documentation, something can be a constant and a string and an array, whereas with SymbolKind one must be chosen.
  2. We can use these as search filters with the same name, e.g. you could search over API docs with tag:example (or some similar syntax) in the future.

Helps #22326 (closed)

Signed-off-by: Stephen Gutekanst [email protected]

Merge request reports