Hi Peter,
there was no agreement - so we rolled back for Pharo 4 to discuss/decide for
Pharo 5.
I communicated already how I would solve it to get IMHO a consistent and
easy understandable solution:
1. executable example
=====================
We talk about executable code here: an "example" in the traditional Smalltalk
sense
means ONLY a runnable piece of code to demonstrate something. Since a long
time and not only in Pharo this
is typically done in methods with prefix "example". It is important to note
that these methods COULD BUT
MUST NOT RETURN an instance. Usually such a method is only there to
demonstrate code.
These methods with the "example" in the name are currently honored by
Nautilus with the
clickable icon. See SystemProgressMorph>>exampleChangeLabel or others.
=> To not be limited to the prefix in the method name I proposed to be able
to additionally use the <example> pragma to mark example methods.
This way you can choose the method name freely to give an example to others
on how to use them.
2. returning examples
=====================
While some example methods just demo code and code usage (like "Job example"
or "BorderedMorph exampleGradient")
a subset of them directly return an instance of the method defining class
(like LabelMorph>>example).
The idea of the GT Tools is to call these methods and display the return
value as inspectable "instances" in the tools,
so for instance if you inspect class VirtualMachine or Character you get a
tab entitled "E.g." where you can click on
these sample instances.
GT and (because GT )now latest Pharo currently still uses "gtExample" method
prefix or <gtExample> pragma to mark such methods and there
is also to wish to remove the "gt" prefix. But with this we would have a
clash with the other "exampleXXX" usage.
=> I would propose to mark the code examples that return an instance with an
<exemplar> method.
According to Google definition of <exemplar> noun - "a person or thing
serving as a typical example or excellent model."
Urban dictionary defines <exemplar> as "a typical or standard model or
specimen"
So I proposed and still propose
- "exampleXXX" prefixed methods and <example> pragma for traditional examples
as used in other Smalltalks and Pharo before
- "exemplarXXX" prefixed methods and <exemplar> pragma (mark code that return
an instance always) for the future inspection
of exemplars in the tools
Thanks
Torsten
