* How do you know when a library is well designed?
The answer for me at least in part is:
* Can I, starting with a blank sheet of paper, easily explain what this does?
I've lost track of the number of times I've redesigned something because it failed that test.
There is currently a mini-repeat of the Outcome v1 review happening on std-proposals. Many of the same points being made there by the uninitiated expert as was made here back in May. Same progressions of understanding. Same arrival at the same conclusions. It's encouraging. But also slightly surprising, the simpler the concept, the harder it seems to become for people to grok it in a strange way. But it also contradicts what you just said. You can very easily explain a library e.g. ASIO. It's a networking library. Done. But does that have much relation to its good or bad design? Same goes for Expected|Outcome. It lets functions return a T|E, like std::variant. But is the Expected or is the Outcome design good or bad? What are the merits and disadvantages of each design decision? How do you weigh them?
The problem I see then, is that tools that extract documentation direct from code have the effect of disengaging the authors brain from the task of explaining what their code actually does. Well it does for me anyway ;)
I've also come to the conclusion that standardese does not make good documentation - despite having authored more than my fair share.
Standardese as in the word soup they put in the C++ standard is not documentation. I tried my hand at writing some of it for the operator try proposal, and immediately got nit picked on lots of bits in it. I'm no language lawyer. I care about *themes*, shapes, forms, fit like any library not compiler developer. Nit picky detail for me is just punctuation, to be added or removed as needed so long as it doesn't break ABI. Which is why I'm not on WG21! Nor would be much use there I should think. But Standardese the tool for generating reference API docs is a large improvement on doxygen, and once it matures quite a bit ought to be very useful for Boost type C++. Be appalled, after all, at how useless the doxygen "extract all" dump of Outcome v2 is: https://ned14.github.io/outcome/doxygen/namespaceoutcome__v2__xxx.html. Far too much implementation detail, it's useless. But Standardese the tool once we get it working ought to chop that very nicely down into the "just right" balance between detail and need-to-know-this. And being pretty in presentation and disability friendly doesn't hurt. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/