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?)

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





Reply via email to