github / github/codeql

Module indexes for documentation

Offen
#18,958 1 Kommentar 0 Reaktionen 1 zugewiesene Person Beansprucht von @adityasharad Auf GitHub ansehen
Vorherrschende Sprache
CodeQL
Sterne
10.1k
Forks
2.1k
Ø Merge
2 T. 15 Std.
Gemergte PRs (30 T.)
141

Beschreibung

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).

Beitragsleitfaden

Beitragsleitfaden öffnen

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.