> On 16 Sep 2016, at 10:02, Guille Polito <[email protected]> wrote: > > Hi, > > I was thinking on the metro way to work, and I also saw that this discussion > is actually split in multiple threads, so it was not easy to follow :). > > Some of my feelings about this: > > - Pragmas are nice because they are easy to "interpret". Parsing them is > already provided. However, putting expressions or long examples into them > starts to be awkward. It seems it's pushin the syntax too much, isn't it? > > - Comments are nice because they are ignored! But right now comments are > simple plain text. This thread is to convert *some* comments into executable > examples. But this should be just some comments and not all of them, am I > right? So what happens when we want to have comments written in Pillar for > example? What I mean is that having examples is just an example of something > we would like to do with comments. > > But we can also imagine having comment interpreters. Something like this: > > ">>>PillarDoc > !This is a Pillar title > And I'm just a paragraph > And I can link a class like @Object. > " > > > ">>>ExampleDoc > self assert: '/foo/gloops.taz' asFileReference basename equals: 'gloops.taz' > " > > What I like from this is that: > - comments that do not specify an interpreter are just plain old text. Thus > backward compatible. > - comments that specify an interpreter that is not present, are just plain > old text. A decoupling as it happens with the settings. > - an ExampleDoc interpreter can be just a test case instance, thus we could > use assertions instead of special >>> messages. > > Things that would require more thought: > - there is an overlap between these interpreted comments and pragmas... > There are for sure cases that solutions can be imagined with both. > - there is an overlap between examples and test cases. I saw many people > that argued that already. I am not against examples, but I think we should > (whichever implementation is chosen) draw a line and set some guidelines. > Stef, probably you have already in mind when you want a test case and when an > example and what's the distance. It would be good if we can transform that > implicit thought in something explicit (maybe even a lint rule in the future?)
+1 to all :) Esteban > > Guille > > -------- Original Message -------- >> Hi nicolai >> >> >> I was thinking that I would prefer to have >> >> "` '/foo/gloops.taz' asFileReference basename -> 'gloops.taz'.`" >> >> >> instead of >> ` '/foo/gloops.taz' asFileReference basename -> 'gloops.taz'.` <- >> suceeds, no output >> >> So that we can use ` in the future in plain code. >> Also it has the advantage that it is backward compatible. >> >> Else we could have >> >> `` >> But I do not know. >> >> Tell me what you think. >> >> I would love to browse the complete system to convert existing one liner >> with such >> >> Stef >> >>> >>> Ok, this is a quick hack ( do not look at the code :), yes using regex here >>> is a bit fragil) >>> >>> You can add code in comments between backticks (`) >>> The formatter will highlight the text like smalltalk code (or not if it is >>> not valid code). >>> + an icon styler with an icon showing a warning icon for faulty code or an >>> information icon otherwise >>> you can click on the icon, >>> >>> if the code is an association >>> >>> expression -> result >>> >>> it executes the expression and compares it with the result, (with >>> assert:equals: ) opens debugger if it fails and does >>> nothing otherwise >>> >>> if the code is just an expression, it opens an inspector. >>> >>> This is just one way to do some tests and experiments with this idea, don >>> 't yet know if this is a good idea or if >>> we can / should find a better way to connect code with examples. >>> >>> first result, I find expressions in comments, highlighted as code, >>> confusing :) >>> >>> (file in attached cs in a recent pharo 6.0 and look at the method >>> AbstractFileReference>>#baseName . Or >>> add an expression with backticks in a method comment >>> ` your code here ` >>> >>> >>> >>> >>> Stef >>> >>> >>> >> >
