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.