Documentation improvement suggestions from Reddit

[ned14]

From https://www.reddit.com/r/cpp/comments/10tt5nw/comment/j7ezsof/?utm_source=share&utm_medium=web2x&context=3

When someone searches for the library what he is see is github readme page of the project first.

And he expects to see list of main features, platforms support + short examples how library works for typical operations, links to more advanced examples and build/cmake/project notes.

Less often, a person will follow links to another readme page.

On your doxygen readme page you have a description that is more likely to scare away the user as an OP.

Next follow not clear features list. After it there two strange examples for rary cases. And all this just gives the feeling that OP is experiencing.

As simple and clean example you can see https://github.com/mandreyel/mio readme.md

And documentation in most cases is more user-friendly if you will use something like MkDocs(based on Markdown), example http://rapidjson.org/

For a starter you can show basic operations for:

• regular files, read/write/get stats
• memory mapped files
• work with directories
• async examples
• some small, advanced techniques
• links to more advanced examples

[BurningEnlightenment]

And documentation in most cases is more user-friendly if you will use something like MkDocs(based on Markdown), example http://rapidjson.org/

May I make a case for using Sphinx instead of something Markdown-based like MkDocs? reStructuredText (reST) isn't as ubiquitous as Markdown, but I've found it far superior in that it actually builds a symbol database, allowing for intelligent OOB referencing OOB. I could contribute the initial setup for it.

Notable users would be:

• LLVM
• CMake
• myself

[ned14]

@BurningEnlightenment If there were any specific part of the OP's request that is least likely to get done this week, it is the set up and config of non-doxygen docs tooling unfortunately.

I've no specific issue with Sphinx versus other tooling except for the same general issue with all of them: none of them are sufficiently better than doxygen for C++ to make me get excited about them. Outcome uses https://gohugo.io which is much better again than Sphinx at referencing, and it lets you use any mix of structured text formats you like based on whichever is best for the content you are making, and it let me make from the same source https://ned14.github.io/outcome/ and https://www.boost.org/doc/libs/master/libs/outcome/doc/html/index.html which if you look closely, they're absolutely identical except for the styling.

Outcome's reference API docs are hand made however, because the Boost review rejected both previously submitted sets of reference API docs each of which came from a different docs generator. Because docs generators for C++ generally suck, and there is no currently good substitute for writing reference docs by hand. And if you're not going to write them by hand, then doxygen's crappy docs isn't especially worse nor better than those from any other tooling (relative to hand made docs).

I do have a mental note to some day check out a newer clang based docs parser called hdoc and see if it does a much better job than doxygen at parsing (which negatively affects Sphinx/Evolve etc). I had the notion of having hdoc dump its output into a Hugo site, and Hugo would fill in all the stuff which hdoc doesn't do such as search and indexing. I've not found time to do that, but that's my mental note that I ought to go investigate that option some day.

Now, if you'd be volunteering to try feeding some code into hdoc and see if it's become high fidelity enough to substantially improve on doxygen, now you would be getting me excited. Last time I tried was a few years ago, and hdoc just wasn't there yet. You should still be able to see that attempt at https://docs.hdoc.io/ned14/LLFIO/.