ipc[_*]: Generated-documentation (Reference, guided Manual) + example-program gaps.

[ygoldfeld]

The state of documentation is good IMO. The Reference (as generated by Doxygen from source) covers everything (except see below); the guided Manual (as generated by Doxygen from additional not-really-source-but-source files) covers every feature (except see below); significant effort went into these. Plus there's a nice system making the generated docs available: Actions CI pipeline checks-in generated docs into main branch automatically; plus for each Release tag; plus links to these are auto-placed into the web site.

The present ticket covers gaps -- things lacking from the above. I labeled it as "bug," as they are IMO specific gaps we've identified -- not just niceties -- so "bug" would draw attention to it. That said, to reiterate, what is there is fairly comprehensive, meaning these gaps IMO don't constitute a major deficit. (Or not... it's subjective... examples-meant-to-be-examples really would be good to have, in particular.)

The gaps:

• The parts of ipc_shm_arena_lend (a/k/a SHM-jemalloc) under src/ipc/shm and src/ipc/session/standalone -- which are (with the exception of shm_pool_offset_ptr_data.?pp, writted by @ygoldfeld) the parts of Flow-IPC originally written by @echan-dev -- and excluding the test/ parts (which in general do not participate in doc generation) -- are in this state:
  • Everything has a doc header, as required. Great!
  • It has not been run through Doxygen -- doing so would definitely at first issue many Doxygen warnings, which our CI/CD pipeline will treat as errors. Therefore it is fow now excluded from doc generation, manually in root CMakeLists.txt (set(DOC_EXCLUDE_PATTERNS */ipc/session/standalone/shm/arena_lend/* */ipc/shm/arena_lend/*).
  • So, TODO: Go over all Doxygen-facing source code; make any fixes according to Coding Guide/precedent; remove the exception CMake code mentioned above; fix any resulting errors; check output visually; fix any resulting problems.
  • Mitigating factors:
    • The docs are there in comments; just not in the nice generated HTML Reference that builds with Doxygen (including via GitHub Actions).
    • Typically a Flow-IPC user, we expect, will access SHM-jemalloc APIs -- if at all (e.g., just selecting it as the ipc::session alias = enough to enable end-to-end-zero-copy for capnp-encoded messages) -- only through well-documented concepts that are documented. Only when using SHM-jemalloc as a standalone SHM-provider, without ipc::session, would one miss any generated docs. This is fairly unlikely in practice.
      • (But that said, they are public APIs. Plus, the full-reference form of the generated docs Reference -- which includes innards, not just public API -- lacks this aspect of SHM-jemalloc, but by definition it shouldn't).
• In the guided Manual, there are a couple of pages that are marked under construction and don't have any other text (except the intro paragraph). Search for "This page is under construction". As of this writing they are @page universes Multi-split Universes and @page transport_core Transport Core Layer: Transmitting Unstructured Data.
  • So, TODO: Write them.
  • Mitigating factors:
    • These are pretty advanced topics, not exactly the first thing someone is going to use, probably (multi-split thing especially).
    • "Transport core layer" page is pretty well covered in the whirlwind synopsis page @page api_overview API Overview / Synopses (the not-yet-written page links to it for now, near where it says under construction).
    • All aspects of these are well covered in the Reference.
• In the guided Manual, there are lots of code examples in-line in the text. Many of the build-up a program piece-by-piece. There's a pretty high chance this code is correct as well. But:
  • They are not formally tested as such; there could be errors (typos, oversights).
  • There is no actual test/demo program for any of them. (We do have tests and demos, but not these specific items.)
    • The one(s) corresponding to e-session-setup.dox.txt, f-chan-open.dox.txt, and especially g-session-app-org.dox.txt = particularly nice to have available; e.g., one can use them as templates (in the non-C++ sense) for user applications.
  • So, TODO: Add these as example programs (and refer to them as available, in the Manual text).
• In general, while we have some test/demo/example programs, like the link_tests, transport_test x 2, and perf_demo, they are not written as example of fine style and organization but rather other purposes (respectively: basic hello-world link+functionality test, heavy functional testing, benchmarking).
  • So they're usable as examples, but they're not intended to primarily be examples -- and we should have such things too.
  • So, TODO: Add (more) example programs (in addition to the thingies corresponding to Manual snippets, from a preceding bullet point).