Re: [OpenMethod] review starts on 28th of April

From: Peter Turcan (peterturcan_at_[hidden])
Date: 2025-05-02 21:05:17

Jean-Louis,

Thanks for your feedback on my comments. To answer your specific questions:

> On this subject, what do you think of Andrzej's distaste of the Animals
example?
> And my motivation for it? I don't want to put my words in Andrzej's mouth,
> you'll find that dialogue easily.

I think the Animals scenario is not relatable enough for a developer
scanning libraries for one that might help them out. The scenarios I like
best are:

1. the new file format I included in the proposed introduction
2. adding new UI widgets in a GUI framework
3. new behaviours (AI, physics) to types in a simulation or game engine
4. extending a logging system with new output

I am assuming the main use of your library is enabling developers to plug
in new behavior by adding subclasses or overriding virtual functions,
without breaking or editing the system’s core - though I do like the idea
of adding a "multiple dispatch" scenario or two as it shows the wider
flexibility of open methods - though the use-cases here seem much narrower
and so specific they might seem contrived.

> I am considering removing the "Reference" level to gain one level.
Instead of:

    Reference
        BOOST_OPENMETHOD
            Synopsis
            Description
        BOOST_OPENMETHOD_OVERRIDE
            Synopsis
            Description

> ...go straight to :

       BOOST_OPENMETHOD
           Synopsis
           Description
       BOOST_OPENMETHOD_OVERRIDE
           Synopsis
           Description

> What do you think?

I prefer having a top level *Reference *heading. It is in a different style
than the introductions and tutorials - and typically is not read in any
kind of order. Most use of a reference is to jump into the topic you are
working on (class, template, macro, method, structure etc.) - extract the
info you need - and then leave the doc without looking outside of that one
topic. This means the reference needs to be complete (as you say "robotic"
in the sense of consistent and complete). I still prefer grouping all types
under a second level heading such as *Macros*, *Templates*, *Classes* etc.

Grouping items "thematically" is the thesaurus approach and has some charm
to it. Works for overviews, tutorials, architecture descriptions, but for a
Reference I prefer to group things rigidly (type then alphabetically), but
add a *See Also* heading after each description (say of a template) that
has a list of links to other entries that are thematically relevant - or
perform the inverse operation (open -> close, add -> delete, etc.).

> What are your favorite Boost documentations?

Mostly, Boost library documentation is comprehensive but requires a higher
level of assumed knowledge than I would like to see. The usual culprits are
an Introduction that does not describe the purpose of the library, or code
definitions/examples or output that has no descriptive text. Make it easy
for your potential developers by adding descriptive text to just about all
entries of source code, syntax, diagrams or output.

Some good library Reference sections are in Boost.Hana and Boost.Geometry -
note the one sentence introductions to each construct, description of
parameters and return values, often an example - all good to see.

> You seem to agree with Andrzej. By the way (BTW ;-) ) he likes YOMM2's
intro
> better. Can you take a look and tell me what you think?
> https://github.com/jll63/yomm2

Yes it is better - especially the detailed list of differences from the
stated paper. However, it still lacks relatable use-cases (even as simple
as the four I listed in this mail would be great to see - or another list
if you have better scenarios) - and it refers to essential information via
a link to a paper. If this link breaks (say the site admins "forget" to pay
their annual hosting fee!) then essential information is lost. Better to
paraphrase the paper into a paragraph or two (or bulleted list) to capture
the essential concepts - and provide the link for more detailed info.

- Peter

On Thu, May 1, 2025 at 6:51 PM Jean-Louis Leroy via Boost <
boost_at_[hidden]> wrote:

> Hi Peter,
>
> Thanks for your review!
>
> I'll think about your remarks on the introduction, and probably blend some
> of it
> in.
>
> > To be clear - does the library implement ALL the features of the N2216
> > paper - if not all, then list those implemented.
>
> I'll add a dedicated top-level entry for this. Probably it should not be
> too
> close to the top, because it will speak to more hardcore users, not to
> people
> who are just discovering open-methods and who have no awareness of N2216.
>
> > It is totally OK to provide references, though expect some reference
> links to
> > break as time passes. *Required information should be in the library
> doc*.
>
> Ok.
>
> > A kinda nit - this is funny "You wanted a banana but what you got was a
> > gorilla holding the banana and the entire jungle." - but - is it really
> true?
>
> Yes it is :-D
>
> Take the Matrix example, where you want to add serialization to the matrix
> hierarchy. If you plant a `virtual void to_json(std::ostream&)` in the base
> class, and implement it in the subclasses, any consumer of your matrix
> library
> will drag in the iostream library. Matrix is the banana you wanted. The
> iostream
> library is the gorilla. You'll pull iostream's dependencies in as well.
> Jumping
> from hierarchy to hierarchy in that fashion, you'll pull much of the entire
> jungle.
>
> People did a lot of this when OOP became mainstream. Later patterns,
> principles,
> etc were designed to mitigate the problem. Visitors, dependency injection,
> interfaces, etc. Open-methods are a solution, but less clumsy I believe.
>
> GETTING STARTED
>
> > Following the introduction, there should be a *Getting Started* section
> which
> > goes over 1) Requirements 2) Steps to install 3) Dependencies (Boost
> libs, std
> > libs, other libs, etc.) 4) hello world tutorial.
>
> > Getting up and running should come before Tutorials.
>
>
> OK, those should not be relegated to the reference.
>
>
> PERFORMANCE
>
> > Perhaps add a table of performance of some sort that readers can relate
> to
> > - say, comparing an open method to a class method with both doing the
> same
> > thing.
>
> https://jll63.github.io/Boost.OpenMethod/#tutorials_performance does
> that, but
> in terms of instructions, not timings. Working on this project has
> destroyed my
> faith in micro-benchmarks.
>
> > However, they are not really tutorials unless they contain steps for the
> > reader to follow. Step 1 - copy and paste this example. Step 2 - run it
> and
> > examine the output, Step 3 - add this feature and run again. Step 4 -
> > notice how the output has changed...etc. etc.
>
> > It would be most useful if the tutorials related to the use-cases first
> > introduced, showing how the desired results are achieved.
>
> On this subject, what do you think of Andrzej's distaste of the Animals
> example?
> And my motivation for it? I don't want to put my words in Andrzej's mouth,
> you'll find that dialogue easily.
>
> I do see his point.
>
> > TERMS and ACRONYMS
> >
> > Acronyms are introduced that I am unaware of, without an initial
> > explanation. For example,
> >
> > Unlike function declarations, which can occur multiple times in a TU, an
> > overrider declaration cannot.
> >
> > What is a TU? Can this be defined in full on first use? Similar for ADL,
> > AST, CRTP etc. And for terms such as "guide function" - add a definition
> on
> > first use.
>
> I *think* I kept the acronyms to the "advanced" parts of the doc. I think
> that
> any moderately advanced C++ programmer knows what ADL is...but I will make
> sure
> that in any given section the first mention of an acronum is: Argument
> Dependant
> Lookup (ADL).
>
>
> > I would really like to see the Reference further divided into sections
> > based on type:
> > * Classes
> > ** fields
> > ** methods
> > * Interfaces
> > * Structures
> > * Constants
> > * Macros
> > * Functions (if external to any class)
>
> So, I struggled with this. I opted for a "thematic" grouping - putting
> strongly
> related constructs close to one another in the sidebar. But that grouping
> jumps
> across categories. Some facets are templates, some are classes. Should
> they be
> scattered between templates and classes? This approach seems to work well
> only
> for the macros.
>
> > - Currently we have to examine each entry, or guess (I don't like
> guessing)
> > what each entry is.
>
> Yeah I experimented with other schemes, trying to get guidance from other
> adoc
> based documentations. There are many variations.
>
> I tried prefixing every entity with its category - e.g. "class template
> method",
> "class template method::override", but this causes a lot of wrapping in
> the left
> sidebar.
>
> I am considering removing the "Reference" level to gain one level. Instead
> of:
>
>     Reference
>         BOOST_OPENMETHOD
>             Synopsis
>             Description
>         BOOST_OPENMETHOD_OVERRIDE
>             Synopsis
>             Description
>
> ...go straight to :
>
>        BOOST_OPENMETHOD
>            Synopsis
>            Description
>        BOOST_OPENMETHOD_OVERRIDE
>            Synopsis
>            Description
>
> What do you think?
>
> I like adoc but it can be limiting...
>
> > If references are arranged alphabetically within each section (Classes,
> > Macros etc.) - they are easy to locate.
>
> In YOMM2 I have a flat alphabetically ordered index
> (https://jll63.github.io/yomm2/#index). Maybe thematic grouping is a bad
> idea.
> After all it's a reference, not a novel.
>
> > ERRORS and EXCEPTIONS
> >
> > It is not clear to me what errors or exceptions might be thrown by any of
> > the entries. All errors/exceptions thrown by the library code should be
> > listed under the entry that might fire them. For maximum usefulness,
> > include a table of errors and exceptions and* what you should do about it
> > if you get such an error* could be described too - say likely causes and
> > likely resolutions.
>
> It is hard to document accurately because of the customization points.
>
> > A complete structured Reference, with descriptions, return values, use
> > cases and errors would be great to see.
>
> Do you mean this style (from Variant2)?
>
>     Effects:
>         Initializes the variant to hold the same alternative and value as
> w.
>
>     Throws:
>         Any exception thrown by the move-initialization of the contained
> value.
>
>     Remarks:
>         This function does not participate in overload resolution unless
>         std::is_move_constructible_v<Ti> is true for all i.
>
> I tried it. But it is difficult to squeeze the library's flexibility into
> this
> mold. In case of error, it aborts. But before that it calls error handling
> facet. Which can throw, or not - it's a customization point. I guess I
> could
> have a Errors instead of a Throws:
>
>     Errors:
>         Call the error handler specified in the policy's error_handler
> facet,
>         then call abort.
>
> More importantly, I felt that this style is robotic.
>
> What are your favorite Boost documentations?
>
> > ACKNOWLEDGEMENTS, REFERENCES
> >
> > The documentation could end with any acknowledgements (designers,
> testers,
> > motivators) and References such as N2216 and no doubt others.
>
> Yes.
>
> > The documentation as it stands describes what the code does but almost
> > entirely from an inward looking perspective and almost never addresses
> the
> > "when I should use this" from a use-case - or more likely a component of
> a
> > use-case - perspective.
>
> > 1. an introduction explaining the "why I should be interested" with some
> > compelling use-cases. The more relatable the use-cases, the more
> interest and
> > users you will get.
>
>
> You seem to agree with Andrzej. By the way (BTW ;-) ) he likes YOMM2's
> intro
> better. Can you take a look and tell me what you think?
> https://github.com/jll63/yomm2
>
> > 2. Are there other Boost libraries that play well with OpenMethods -
> even if
> > you have limited experience of this a start would be helpful.
>
> Yes.
>
> * Using a flat_unordered_map in place of a std one. That brings dispatch
> speed
>   closer to my perfect hash solution.
>
> * Interoperability with intrusive smart pointers.
>
> > I hope my 2c is useful.
>
> You are a technical writer, I am a just code writer trying to do a
> technical
> writer's job. That's worth a lot more than 2c ;)
>
> J-L
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>