Hello! I have read bunch of documentation related to clang-tidy and I feel like the current documentation could benefit from the following points:
Add the expected type for each check option value (string, integer, floating point number, list, etc).
Add the first version of clang-tidy that supports the check and its options. As of now, it’s hard to know which option is supported by clang-tidy if we look at the official documentation and we either need to read the documentation of the clang-tidy version we’re using (which probably mismatches the one from the official documentation so it requires to download the sources archive) or use the verify-config. Unless I’m missing something? clangd and clang-format have this feature in their official documentation so I thought it would be nice to have it for clang-tidy as well.
Add the default values for each check option, in a common format. For some check options, they are not specified in the documentation so it’s hard to know which default value is used (it requires looking at the source code which is quite inconvenient). When the default values are specified, they are not always formatted the same way and I feel like it would be better to use a common format so it’s more clear for readers.
Add a drop-down menu to pick which documentation version we want to look at.
I would like to contribute to this project so I was actually thinking about starting to work on all those points but before starting to get into it, I wanted to make sure this would be ok with the community/project leaders so I don’t start working on something that will not be merged anyway. I would be glad to know what you think about this so feel free to let me know!
Hi, thank you for proposal, generally this could be a great improvement for the project so LGTM. Speaking for implementation, you can create a draft PR with a small example and so we could discuss the design and then make changes to all checks.
For me the most important and great to start with is
For ease of review, I suggest a script that computes a diff between --list-checks and --dump-config of two clang-tidy versions. Otherwise, it could be hard to manually verify correctness.
I think we try to write in each option what format it expects. E.g. “list of semicolon separated values”, etc. But for sure we can add a type next to option name and see how it looks/helps.
I tried to address this issue in the past. The default value of the option must be at the end of the option description with sentence “Default is xxx”. We require it for all new checks. I’m open to see a preview with new format a discuss in PR.
Thank you for your answers @vbvictor! I was thinking of making one PR per bullet point so it’s probably easier to review and faster to merge. Regarding the following point:
Add the first version of clang-tidy that supports the check and its options.
I was indeed thinking about making a script to automatically detect that (it would work a bit like git bisect does), it would be much faster to do it that way and also less error-prone. I will link the PR draft here once I start working on it
Thank you, I’ll make to refer to this issue once I start working on it. Are you still working on it though @weirdsmiley? If you do, I’ll leave it to you!
Hi, I haven’t worked on it yet. You can pick it. If you feel other pointers will occupy you, then you can skip the last one. I’ll work on it.
In a previous discussion, we were thinking of adding a table-like structure to hold previous documentation versions for clang-tools-extra. Drop-down menu sounds better.
About 2 years ago, I opened an issue proposing the same suggestion:
Back then, I suggested that LLVM use the CMake documentation’s version switcher for reference. However, after conducting the research on the localizethedocs, I now believe the RTD’s flyout navigation menu is a much more suitable and generic option.
I agree, since localizethedocs already features a flyout navigation menu for switching language/version, it’s probably better to use that directly. However, for now, it seems we can only switch between major versions. Could we also allow users to switch between minor/patch version within major versions (e.g., v21.1.3, v21.1.2, v21.1.1, v21.1.0 and so on)? It would be nice to have consistency between the releases available on the official GitHub repository and the versions available from that flyout navigation menu.
I think this is not really necessary. We don’t add new features in minor releases and hardly have any bugs that are patched. AFAIK in 21th release we didn’t have any patches in all minor version, so the pages would be identical. Thus I don’t think we really need dedicated pages for minor versions
