Missing reference documentation for configuration parameters

[hw0lff]

Possible values for the enum typed parameters and their descriptions are not shown in the rust analyzer manual.
In the Configuration section of the manual are only the names of configuration parameters, their description and their default value displayed.
The configuration parameters are not just booleans. They contain number and enum types too.
These two types are missing important parts of their documentation.

For example:

1. The entry of the number parameter cachePriming.numThreads is lacking that this parameter only accepts values between 0 and 255.
2. The entry of the enum parameter lifetimeElisionHints.enable is missing the possible values it can take and their descriptions.

No one is able to correctly guess what options it can hold and finding out the possible values is very time-consuming and impractical.
Right now I have to look into editors/code/package.json to get a look at all enum options and their descriptions.

The required information is technically already existent in that package.json. The most obvious solution would be to somehow generate the documentation from the package.json.

P.S.: I had to manually find out the anchors by looking at the html source. Is there any way to make this easier?

[hw0lff]

Can someone add the A-documentation label?

[hw0lff]

Here is a proof of concept. Is there any other way I or someone else can assist the implementation?

[HKalbasi]

The code that generates the config is this.

[hw0lff]

Based on what is happening in #13529, #17058 and #17101 it seems to me that there will be multiple ways to configure r-a.

I would like to state my current opinion on requirements of an improved reference documentation.

Requirements

The overall goal is to provide a better usability for everyone.
Web documentation is the one common and editor-independent ground between all users.
And therefore must contain all available documentation.
Editor-specific built-in documentation must never contain more information than the web docs provide.

1 Completeness

All parameters must be documented.
Everything that concerns the parameter must be documented at the parameter's paragraph.
This includes their description, configuration scope, its possible types, possible values, (numerical) limits, defaults, etc.
Jumping between multiple doc pages to get the full picture of a parameter must be avoided.

2 Discoverability

The intention is to give users the possibility to search for what they need with their own tools (e.g. browser built-in page search) and to not force them to use an opinionated, even perhaps subpar, html+js search bar.

To achieve this the reference documentation needs to provide these two types of pages:

1. A single page with every parameter in it, regardless of configuration scope, with the above stated information.
2. A separate page for each configuration scope containing only parameters of that scope.

Both types of pages must have a table of contents.

The second type of page could be substituted by a page containing only a table of contents linking to parameters of that scope.
However, being able to search all text of a single scope's parameters is useful too.

3 Referenceability

r-a currently has 175 config options. The documentation pages will be long.
No one would be able to navigate these huge pages without anchors/links.
The TOC's elements need to link to their respective parameter section and every parameter heading should have an anchor to itself.
This makes sharing and, in general, referencing specific parameters easier for everyone.

[hw0lff]

We will want to automate the generation of web docs and vscode package.json config options.
Having a single source of documentation truth would make this a bit easier.
It also means less fiddling with the package.json by hand and web docs won't contain less information than the package.json

[hw0lff]

I doubt that everyone has access to the latest version of r-a.
Sometimes people may need the documentation of old versions,
which is why we should build them and make them available, following the requirements above as best as possible.

[Veykril]

Yes, this is absolutely on my list of things to target next, the documentation / manual hasn't been kept up to date with things and general deserves some love, especially with the introduction of the rust-analyzer.toml now as you pointed out. I'm planning on getting #15795 merged next week at which point we can start tackling the things you've laid out here (and more).

Thanks a lot for stating your opinion here :)

[hw0lff]

FYI I updated the proof of concept package.json renderer to work with multiple configurations. See nightly for a preview.