Re: Overloading by Example (pieces)

[tye]

That looks less clear to me than first introducing the sample code that uses an overloading module, then showing the code that would be called by such an overloaded operation, then showing the preamble needed to set up such a module.

Your example is certainly easier to just glaze over when reading, cut'n'paste en-masse, and then futz with the code without bothering to try to understand the basics of overloading, just trying to get something to work. But I'm not sure that is an improvement as far as documentation goes.

I'd like to see more examples in documentation, but I'd rather have small examples that each explain one concept rather than one monolith example that I'm supposed to dig through trying to find the concepts.

[Ovid]

What you're describing is more tutorial in nature than an example I'm suggesting. I could cut it down more, but let's compare it to the SYNOPSIS from overload:

        package SomeThing;

        use overload
            '+' => \&myadd,
            '-' => \&mysub;
            # etc
        ...

        package main;
        $a = new SomeThing 57;
        $b=5+$a;
        ...
        if (overload::Overloaded $b) {...}
        ...
        $strval = overload::StrVal $b;

Let's see:

• It doesn't compile
• It uses the bad indirect object syntax
• It uses two of the least commonly used functions
• It doesn't show the implementation

No wonder people are confused by overloading! Whenever feasible, I feel that a synopsis should have code which can be cut, pasted and run.

My example is "monolithic"? You'd think I'd written a framework or something ;)

[tye]

You seem to misunderstand the purpose of a synopsis. Your example certainly doesn't make a good synopsis so comparing it to the synopsis makes little sense to me. Was it meant to be a replacement for the synopsis? It contains too much that isn't paritcularly relevant to the summing up. To me, wading through your example looking for the important concepts doesn't seem to be much of an improvement over wading through the documentation looking for the important concepts that you were complaining about (there is less to wade through but little to point out where the important concepts are and most of the code is rather irrelevant to the key concepts).

There are already examples of the use of overload.pm that compile (as you found) so I'm not sure adding such a contrived example of that directly to the documentation is a good idea. If the point is to explain the key concepts (which seemed to be what your point was), then I don't see how being "more tutorial in nature" is anything but a good thing.

So I see more value in 1) few-line examples concentrating on fewer points and accompanied by explanatory text and 2) much less contrived complete examples in an "ex" subdirectory. An example implementation of each type of method in the section that talks about that type of method would be a welcome addition. Having to wade through your "complete" implementation in order to find such just obfuscates the key concepts (and does a poor job of documenting many of the important points of such methods and of demonstrating how to write a useful overloaded object).

[eric256]

Perhaps this is all only because you are more familar with overload already? I know that when I read the documentation for overload the first few times it was worthless to me until i found a complete example. If such a complete example where found in the documentation then I know my life would have been made easier. I'm particularly confounded by modules that have code in their synopsis that can't be used as is. If i have to read the code, read the documentation and then figure out how to modify the code to get a basic sample working , then I'm far less likely to succeed in using such a module. Modules that give good self documenting examples somewhere in the documentation are much much easier to pick up and start learning. Perhaps its just a difference in learning technique, but i like to start with working code that i can futz with, not futz just to get working code.

It probably would be better to leave any extra modules out of the example though.