Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-10-09 17:25:24

On 10/7/17 3:09 PM, Niall Douglas via Boost wrote:
> 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?

I think you're wrong here.  ASIO is a good example.  Documentation gets 
off to a good start.  A clear state as to what it's intended to so.  But 
since it does thing somewhat differently to what people have experience 
with, it's hard to explain.  I think it's explains how to use it pretty 
well, given these circumstances.

Expected/Outcome - a whole different kettle of fish.  The idea is simple 
and familiar. But I don't think there is agreement on what the proper 
use cases are for such a thing. So problems arise since different people 
want to overload the idea with more "features" and then one can never 
agree. I'm wondering a couple of things.

Would this be helped by characterizing Expected/Outcome as something 
like ... "to be used as a resultant type by an operation which might 
fail" or some such?  This would make all the arguments about what 
happens on assignment out of scope.  Of course now people would say the 
scope is too narrow.  etc.....  The "reviews" of these ideas tend to try 
to generalize them - generally a good thing - but not always.  Some 
times the attempt to reconcile all the requested features results in a 
watering down of the original good idea.  When a simple idea like 
Outcome/Expected generates documentation of more than 4? pages, it's 
time to step back and ask oneself whether we've lost our and turned our 
original elegant idea into a monstrosity.

Robert Ramey