Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This commit adds a `docgen` binary to the tools crate. This tool can generate a .json file describing the API based on parsing the `cbindgen` generated `rustls.h` header file using a tree-sitter C grammar. The produced JSON can in turn be used to generate markdown web documentation, or any other format required. Along with generating docs this tool applies some basic policy. In particular it requires that **all** public API items be documented or it will produce an error instead of the JSON data. We can extend this in the future to require (for example) describing arguments and return values in doc comments. The generated JSON has the following structure: ```json { "structs": [ .. ], "functions": : [ .. ], "callbacks": [ .. ], "enums": [ .. ], "externs": [ .. ], "aliases": [ .. ] } ``` Where each key is a general category of item: * Structure definitions * API function prototypes * Callback typedefs * Enum typedefs * Extern typedefs * Simple type alias typdefs Within each category items are described like: ```json { "anchor": "rustls-accepted", "comment": "A parsed ClientHello produced by a ...", "name": "rustls_accepted", "text": "```c\nstruct rustls_accepted\n```" }, ``` The anchor field is useful for creating anchor links that identify the item. The name is the actual name of the item. The comment is the C block comment content (with the block comment syntax removed, but other whitespace left as-is). Lastly the text field holds the actual text that defines the item in rustls.h (without comment) as a C formatted markdown code block.
- Loading branch information