github / github/codeql

Module indexes for documentation

Ouverte
#18,958 1 commentaire 0 réactions 1 personne assignée Réclamée par @adityasharad Voir sur GitHub
Langage dominant
CodeQL
Étoiles
10.1k
Forks
2.1k
Merge moyen
2 j 15 h
PR mergées (30 j)
141

Description

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

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.