Hi Tudor,

stay serious: the methods you are talking about were introduced as GT extension following YOUR definition of
an example.

We could argue what/who was first with <example>, who discussed/patented it first, who has to change the most
code now ... but would it move us forward? We do not need a long discussion, we need a solution.

The situation is that we have a conflict in the usage of <example> Pragma:

�� ��We wanted a way to find out the examples given in methods (often hidden in the image and external packages)
�� ��and also remove the limitation that they have to start with exampleXXX.
�� ��So I took action to be able to explicitly mark methods that are intended by the author as
�� ��an "example" by using the <example> pragma. This was integrated in Pharo 4 and is also in use, not in
�� ��the image but in loadable packages already. My definition of an example is "a general code example".

�� ��You had another discussion in the context of GT Tools about renaming the <gtExample> into
�� ��<example> and also meanwhile took action to use use <example>.

�� ��But you also put the ADDITIONAL meaning behind the pragma that methods marked with <example>
�� ��should always return an initialized object.

And this last part is the only part where our point of views collide. There is no need to explain from your side
that it is often valuable to have such example methods that return initialized instance. One can use
them to construct other initialized instances, ...

Anything I say is that not all "examples" and "example methods" are providing such example instances.
So we can not (and should not) ignore the fact that not all methods intended by the author as "examples"
follow this additional definition/requirement.

So the only difference in our point of view is that you want to mark all of them equally with
<example> and assume that all of them return an instance of the same class while I will not
because not all examples do that. Some of them are just example methods to demonstrate how
to use the class or combine objects or do some action where the return value of the method is
uninteresting.

So in your definition of <example> pragma you talk about the need for marking methods
with "example instances" while I talk about more general examples (examples of code) that
can but do not necessarily have to provide such initialized instances.


So my proposal is simple and should satisfy both needs:
=======================================================

�� 1. The <example> Pragma can used to mark a method as an "example" method. An example
�� �� ��is a method that is intended as an "example of code":

�� �� �� �� tryThisOut
�� �� �� �� �� ��<example>

�� �� �� �� �� ��Transcript show: 'An example on how to write to the transcript'


�� 2. The <exampleInstance> Pragma can be used to mark methods that return an
�� �� ��an example instance:

�� �� �� �� anInstanceA
�� �� �� �� �� <exampleInstance>

�� �� �� �� �� ^$A


This will solve the issue easily and it will be more clear as THE INTENTION OF THE PRAGMA in
both cases FITS WITH THE NAME. Also a tool can query for one or both pragmas and decide if
if it wants to inspect/display the result after performing the method or just run it.

So this is my proposal to satisfy both POV's. You can argue agains it but not without
making another proposal that satisfies both needs.

Thanks
T.