github / github/codeql

Module indexes for documentation

Abierto
#18,958 1 comentario 0 reacciones 1 asignado Reclamado por @adityasharad Ver en GitHub
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

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.