On 30/01/2017 10:24, Niall Douglas wrote:

Bah, forgot the links:

Part A: file:///C:/Users/ned/Documents/boostish/outcome/doc/html/md_doc_md_02-tutorial_a.html

Part B: file:///C:/Users/ned/Documents/boostish/outcome/doc/html/md_doc_md_03-tutorial_b.html

By which I really meant: Part A: https://ned14.github.io/boost.outcome/md_doc_md_02-tutorial_a.html Part B: https://ned14.github.io/boost.outcome/md_doc_md_03-tutorial_b.html So sorry, I'm late out the door to work. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/

The current form is much better than the initial version. It was easier to skip the parts that I do not care much about, and easier to follow what the goal of the library was. As someone who hasn't read anything about expected before, it was nice to have a section on it.

I overall liked the code examples, they worked much better for me than the previous ones.

Great. They're surprisingly hard to get right without annoying people.

However I do think the name "Tutorial" is a bit of a misnomer, and the parts A, B and C should be renamed to "Background", "Rationale" and "Introduction" respectively (or something similar). Most of part C is introducing the API, and the full tutorial bits, when ready, really should stand out a bit more compared to the current A, B and C sections.

Feedback has been pretty universal that people want an expected implementation and they don't really want anything other than that. Hence Outcome is now primarily an expected implementation, which is a bit sad for me personally, but hats off to Vicente and all that effort he's put into WG21 on getting Expected to where it is. Hence Part A really does need to be a tutorial of some form. Part B, thanks to Reddit feedback, is going to mutate from a polemic against certain naive use practices of expected into a more "this is the way we really strongly suggest you ought to use expected instead of what you thought you would do". That then segways into Outcome's refinements which are basically hard codes of the best practice.

Going back to the start, I think rephrasing the initial portion of the description section to focus on Outcome rather than expected would be beneficial. As it reads now, I still come away from this thinking it's a helper library to expected, rather than something that could very well be used on its own.

It's okay by me if Outcome becomes perceived as an Expected implementation with a few extensions and helper utils. It's definitely what people want, and I'm a believer in giving people what they want even if I don't personally think it's good for them.

Now I'm just a n00b, but I get worried about the raw char*'s everywhere. I know you're aiming for maximum speed, but couldn't the interface have std:string overloads as a safer alternative? At least for things like error_code_extended::extended_message(). I don't generally care much for the brute-force performance of my error handling code, it's not the hot path.

Agreed. I intentionally left them out for the peer review because if I include them then they form part of the review, but you can expect string_view and gsl::span<> overloads to turn up if Outcome is accepted into Boost. Also, some really do care about maximum error handling performance, specifically me because AFIO v2 needs failure to be handled as quickly as and equally to success :)

Personally I like that you've removed the word "monad" for most of the documentation. It's one of those concepts I sorta know what is, but I still have to do a web search each time just to remind me. Though in part C one is introduced to monad_error and friends. Now, _I don't mind this_, however I think it would be nice to have a _footnote_ here to quickly explain where the name comes from, with a link to some page with more info on monads.

Again if I did that then monads would form part of any review. So if a review ever comes, my response will be "the names are just a collection of ASCII bytes". I've already disabled by default half the stuff Outcome can do for the review, and purged any mention of those facilities from the docs apart from suggestive nomenclature.

Anyway, I now got a much better impression of what this library is about than the initial version of the docs. It also presented Outcome as a useful and interesting library, and as something I would want to try.

Thanks very much for your detailed feedback, and I'll incorporate the stuff you suggested that I didn't respond to. I agree that Part A, B and C of the tutorial isn't ideal naming. I'll see what I can come up with instead. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/