Readme documentation enhancements

[spiderkeys]

I heavily use this library in one of my projects (thanks for the great work!), and have become pretty familiar with a lot of its ins and outs, but I had to figure out some of the usage and default behaviours by reading through the source and test cases (the tests are great when it comes to documentation!). I think it might be helpful for a few things to be more explicit in the readme to help newcomers. The intent of this issue is to serve as a tracker for things to add to the readme. I know that these generally exist in doc/index.md, but it can be a bit cryptic and hard to find. Eventually, I will get around to adding them myself and submitting pull requests, but maybe someone else will get to it before me or otherwise demonstrate the lack of need 😄

Topics

• Default constructor and assignment behaviours and examples (move vs copy)
• Differences between accessors ([] accessor will add items if they don't exist, .at() will throw)
• Section on the various exceptions in general

[nlohmann]

Thanks for the input. I am still not happy with the documentation, so far, we have:

• the README which should be more a teaser than a piece of documentation,
• the Doxygen documentation index page which should be some kind of index to find what one is looking for, and
• the actual class documentation where each function is documented with an example.

In the long run, I would love to have the README a bit shorter, the index more complete, and the class documentation as last resort and reference for those who need all the details. Unfortunately, I did not manage to use a Github-like theme in Doxygen, and I am quite unhappy with the way it looks.

Finally, I am not sure whether Doxygen is still the goto-tool when it comes to C++. I don't like the way each function gets a single page, and it would be nice to have documentation like http://en.cppreference.com where, for instance, all flavors of insert are documented at one place.

That said - I am looking forward to proposals on how to improve the current state!

[nlohmann]

Hey @spiderkeys, and proposals how to improve the documentation?

[whackashoe]

readthedocs is a nice option I think, allows people to check the docs out online which is sometimes more convenient.

[nlohmann]

readthedocs is nice if you have lots of plain text, but I haven't seen it nicely document C++ functions in a way like cppreference is doing it. Though all this could be realized by Markdown, I like the approach of Doxygen to pull it out of the source automatically.

(And what do you mean with "check the docs out online"? - the current documentation is online).

[spiderkeys]

@nlohmann
Like you, I also feel like the Doxygen is a bit hard on the eyes and not very nice to use. cppreference does a great job in organizing and laying out their documentation, but I have never run into a documentation engine that creates something of that caliber. Unfortunately, Doxygen has been overwhelmingly the documentation engine of choice in almost all projects I've looked at or used. That said, I do like and appreciate that you have included examples in all of your Doxygen docs, which makes it actually useful in some sense; most people/projects neglect to do so.

readthedocs could be used to make a nice looking document using markdown and codeblocks, but it doesn't seem like there would be an easy, automatic path to generating the docs if you went that route.

Unfortunately, I don't really have any better suggestions for what to use in place of those tools, provided that you would like to keep that info out of the readme. Perhaps the majority of examples could be pulled out of the readme (except for the simplest cases) and an examples folder could be added that handles very specific use cases/scenarios. The doxygen examples do a good job with specific functions, but you do have to go digging. Having a list of aptly named example files could be easier to navigate and get a feel for common use and patterns.

[nlohmann]

I shall try the following:

• Take the XML output of Doxygen.
• Write a tool that extracts the required information from this XML file and create HTML documentation that looks more modern (is quite some work, but easier than to do everything via CSS and other Doxygen templating).
• Find a way to group functions so that I can create documentation pages like cppreference.com where several similar functions are documented in one page.

What do you think?

As soon as I have something to show, I shall open a Github repository to collect feedback.

[spiderkeys]

That sounds fantastic; I could definitely make use of a tool like that myself. Look forward to seeing what you come up with and can provide support/feedback if/when necessary.