github / github/codeql

Module indexes for documentation

Đang mở
#18,958 1 bình luận 0 reaction 1 người được giao Được @adityasharad nhận Xem trên GitHub
Ngôn ngữ chính
CodeQL
Star
10.1k
Fork
2.1k
Merge trung bình
2 ngày 15 giờ
Pull request đã merge (30 ngày)
141

Mô tả

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

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.