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. 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"