On Sat, Mar 28, 2015 at 5:00 AM, Sean P. DeNigris <sean@clipperadams.com> wrote:
Torsten Bergmann wrote
1. use <example> as agreed in October for exampleXXX methods/example methods with different selectors and use <exemplar> for the instance returning methods that I proposed (including a changeset) Stef said it would be OK for him
2. use <exampleOfInstance> and <exampleOfInstance:> as Kilon suggested
3. use <exampleCode> for code examples and <exampleInstance> for the GT extension as Andreas/Christophe suggested
4. use <sample>
Isn't it amazing that we all care so much about Pharo and each other and still create a mess sometimes :) But then we always clean it up! I liked your quoting Pharo zen. I should probably do that more when I get annoyed.
I wasn't going to weigh in because it seemed like it would definitely be pushed to 5.0, but since the discussion is still ongoing. And that's good because: 1) as T. said, if we introduce something for a year it will be much harder to change once people are using it 2) and, as a pragma rename for example code, there seems to be limited risk/work involved (should be easily re-writable no?)
From a native English perspective, for GT I think only #exampleInstance (or almost-as-good #sampleInstance) both sound natural and clearly reveal the intention. For the other "play button variety", #example is fine, but #exampleCode or #sampleCode would be more explicit in light of the two distinct usages now. For simplicity, maybe they should mirror each other i.e. (exampleInstance & exampleCode) | (sampleInstance & sampleCode).
Anyway my 2c
With <example> in dispute and concern with locking in semantics for Pharo 4, it might be pragmatic for both sides to back away from <example> for the Pharo 4 release to mirrored pragmas <exampleInstance> & <exampleCode>. It will be easier to discuss semantics in Pharo 5 for a new <example> rather than modifying and existing one. It should be no trouble to carry forward <exampleInstance> & <exampleCode> for a while before they are "maybe" deprecated. To add a further 2c, I wonder if Pharo 5 might consider parameterising <example>: * <example:instance> or <example:inspect> or <example:returnsValue> * <example:code> or <example:doit> or <example:play> then you might even have <example:inspect,play> @Doru, Sorry I had used a few caps to emphasise some phrases. I didn't consider it shouting unless I typed caps for the whole paragraph. I'll amend how I do this. cheers -ben