On Wed, Mar 25, 2015 at 1:40 PM, Ben Coman <btc@openinworld.com> wrote:

On Wed, Mar 25, 2015 at 7:34 PM, Tudor Girba <tudor@tudorgirba.com> wrote:

Hi Torsten,

I think there can be some value in having example code that shows things beyond just returning an object. However, I think there is significantly more value in examples that do return objects. That is why I would want to have example for the more valuable piece, and to eliminate confusions I would not even call the others example, but another word, like script:

exampleThatReturnsOneObject

<example>

^ ...

snippetThatDoesOrShowsSomething

<script> / <exampleScript> / <exampleCode>

^ ...

I still think that <script> is enough. The goal of these methods is to get the person to run them and observe the side effect, without reusing the result. That is what scripts typically do. It should be enough. As for the example* methods, most of them can be nicely decomposed into an <example> and possibly a <script>. It would be enough.

I'm not sure of the correct solution, but this semantic doesn't feel right to me.�� I've never thought I needed to inspect the result of an example.�� An example "does something", like a doIt.�� I want it to "show" me something.�� If the aim of the example was to give an object to Inspect, then it should explicitly open an Inspector. ��

To me a script is definitely NOT an example.�� A script is something that provides convenience for performing system maintenance. For example, it might change system state by resetting a cache.

The word that I feel best applies to Doru's need is <sample>, to return a fully initialised sample instance that you can play with in the Inspector.�� When you double-click a method so tagged you can think of it as "give me a sample" of yourself.

cheers -ben

��

Here is more reasons why I would not change <example> now. Until now, nobody is really using the <example> except the code that is packaged in GT. The only problematic part is:

TigerDemo>> runDemo

<example>

^ self new runDemo

But this one does not even fit your definition of an example of code. It's merely a way to trigger the running of the instance. It so happens that the class is an example for something else, but this code is not an example. It's a script. So, it should be:

TigerDemo>> runDemo

<script>

^ self new runDemo

(this solution is already committed in the Athens repo)

This would not even be a new interpretation. In the image, there already exists scripts that trigger an example class:

DynamicSpecExample>> openOnNil

<script: '(DynamicSpecExample object: nil) open'>

...

ui openWithSpecLayout: layout.

Btw, the <example> check in the CompiledMethod>>isExampleMethod was added after the discussion about introducing <example> and this tended to unify the meaning with the current example* selectors. We did not catch this distinction at that time, but it is clearly a mismatch. So, the actual intention of <example> did not change at all, but isExampleMethod enforces a new contract on the original one.

So, really, let's not make a larger thing than we have to out of this. We really have *one* problem that is not even a problem. The solution from Athens should be fine now, and we could remove the <example> pragma check from isExampleMethod for now.

Cheers,

Doru

On Wed, Mar 25, 2015 at 9:57 AM, Torsten Bergmann <astares@gmx.de> wrote:

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.

--

www.tudorgirba.com

"Every thing has its own flow"

www.tudorgirba.com

"Every thing has its own flow"