Missing Files

[saraedum]

@tobiashienzsch reported some issue with his library github.com/tobanteEmbedded/tetl:

My Pipeline

• Create markdown files using standardese v0.5
• Run post-processing python script
• Add markdown files to hugo project
• Build static files using hugo
• Demo: tobanteembedded.github.io/tetl-docs

cd tetl/
mkdir cmake-build-docs
cd cmake-build-docs
standardese --config $(shell realpath ./standardese.ini) -I $(shell realpath .) -DTETL_RTOS_USE_STUBS=1 $(shell realpath ./etl)
./scripts/standardese-md.py

Missing Files

Problem: For some files from my library no documentation is generated. An examples is etl/string.hpp, which only generates markdown for the #include statements. Even tough there are a lot of entities inside the file. Source: etl/string.hpp. If I run standardese only on the problematic file I get no warnings or errors. Even in verbose mode.

[saraedum]

The problem seems to be in cppast. Running the cppast tool on string.hpp produces the following output:

AST for '../tetl/etl/string.hpp':
|-etl/version.hpp (include directive): `#include "etl/version.hpp"`
|-etl/string_view.hpp (include directive): `#include "etl/string_view.hpp"`
|-etl/warning.hpp (include directive): `#include "etl/warning.hpp"`
|-etl/detail/container_utils.hpp (include directive): `#include "etl/detail/container_utils.hpp"`
|-etl/detail/string_char_traits.hpp (include directive): `#include "etl/detail/string_char_traits.hpp"`
|-etl/detail/string_conversion.hpp (include directive): `#include "etl/detail/string_conversion.hpp"`
+-TETL_STRING_HPP (macro definition): `#define TETL_STRING_HPP`

[foonathan]

I plan on adding a different backend to cppast (using clang's ability to dump the AST as JSON as opposed to libclang). This will fix a lot of cppast bugs (and probably this one), but it'll take some time before I can get to it.

[tobiashienzsch]

@foonathan I played around with clangs json output last night. The schema is really straightforward. One minor issue is, that it produces a lot of data. The etl/string.hpp header creates a 190 mb json file. I parsed the json output with boost::json. Here is the code. Have you decided yet, which (if any) json library you want to use?

[foonathan]

I plan on using simdjson https://github.com/simdjson/simdjson

It does on-demand parsing, so it only looks at the part of the JSON that match declarations and skips the actual statements.