Module indexes for documentation
- Lenguaje dominante
- CodeQL
- Estrellas
- 10.1k
- Forks
- 2.1k
- Merge medio
- 2 d 15 h
- PR fusionados (30 d)
- 141
Descripción
I think it would be great if standard library documentation included lists of modules present in a namespace. For example, the documentation of the C++ `ControlFlowGraph` module is available here:
https://codeql.github.com/codeql-standard-libraries/cpp/semmle/code/cpp/controlflow/ControlFlowGraph.qll/module.ControlFlowGraph.html
This is easily discoverable _if_ someone knows what to search for, but I couldn't find a good way to find out what other modules are there in the `semmle.code.cpp.controlflow` namespace (the https://codeql.github.com/codeql-standard-libraries/cpp/semmle/code/cpp/controlflow/ URL is 404). Having such a list in the documentation would be useful to find the best fit for the control-flow problem at hand in this case. For example when browsing the source code and reading the comments of each .qll file in the [appropriate directory](https://github.com/github/codeql/tree/main/cpp/ql/lib/semmle/code/cpp/controlflow) one can discover the `BasicBlocks` module [stating](https://github.com/github/codeql/blob/e73745d3ca70768d59ad7e21371ba092b43d88a8/cpp/ql/lib/semmle/code/cpp/controlflow/BasicBlocks.qll#L2C4-L3C99):
> "Provides a library for reasoning about control flow at the granularity of basic blocks. This is usually much more efficient than reasoning directly at the level of `ControlFlowNode`s."
My suggestion is to generate documentation from these comments too and generate index files in each namespace directory that list all contained modules and namespaces.
I'd be happy to work on a PR but I'll need some guidance about how API documentation for the standard library is generated (I could only find [this guide](https://github.com/github/codeql/blob/main/docs/codeql/README.rst#building-and-previewing-the-codeql-training-presentations) that doesn't seem to cover the standard library API).
Guía de contribución
Evaluación
Este issue todavía no se ha evaluado.