Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

+1

I love Sunit as specification validation.
I like doctest just a validated doc. I do not care that the are used as 
tests. This is not the main goal to me

The goal is make sure that the reader understand fast.
I like that there are in the comments because in a PharoDoc the examples 
woudl be there.


Sytef



> On Sep 16, 2016, at 8:37 PM, stepharo > wrote:
>
> + 1
>
> Changing the language metamodel for simple validated
comments is a huge effort for nothing.
> Clement is good at VM level but not at other level :)

I think there is a misunderstanding :). I do not see any
implication to the language meta-model in the remark of Clement.

In fact, I expressed exactly the same opinion, that the design
of things like PythonDoc comes from the fact that those people
do not rely on an IDE, so their design focuses on the only
thing they have: source code. Clement remarked that we already
have SUnit tests and he suggested that we could just enhance
the IDE to present them next to the methods. This might
actually be less straightforward with SUnit because it was not
made for preserving links to the code, but it can work out of
the box with something like GTExamples.


Yes, the language meta-model is already too complex in Pharo IMHO,
let's not make it even more complex. I should have precised that's
not what I meant if this was not obvious to everyone.

/1. Method docs with examples, so a user can see an example usage
of a method (sunit test methods sometimes aren't good "examples")/
/2. We already had (and still have) some method docs where the
example code just won't work anymore because the methods or
classes used/

Nicolai,

I'm suggesting to show the SUnit test code (or example code, or
whatever) next to the method, and being able to create a unit test
this way instead of only the existing green/red button and the
"browse tests" entry in the right click menu. For existing methods
having in their comment executable code to test how they work (as
you mentioned), the code can just be moved to the test shown in
the pane next to it (through a script discovering all cases like
that or manually).

The example usage would still be shown next to the code for the
user, except it would already be under version control as existing
SUnit tests are, it can now have syntax coloring which is not
present in comments, it's automatically executed by each Pharo
build through SUnit hence detecting regressions and the meta-model
is not getting more complex at all. As Tudor said, it's only about
IDE changes.

I believe that some SUnit tests are sometimes not good examples
because they're higher level tests (application tests, business
tests) while as for python doctests it's only relevant to show
unit tests next to the method the unit test validates. Currently I
believe Nautilus discovers tests and add the green/red button
based on name conventions. Foo>>bar has this feature if
FooTests>>testBar is implemented. So it's either a matter of
improving this heuristic or educating the community with this
existing name convention. In any case, I don't think it's more
changes for the user than having to learn convention in the
comments/pragmas.


Yes, we should d some experiments with different solutions and see 
what works.


I like the simplicity of having code in comments, at the moment I 
don't like when we use the code highlighter, because this looks a bit 
confusing.


I would like a better link between methods and sunit tests, too.

I still don't think that unit tests can fully replace code examples. 
And having a possibility to validate the code from method comments 
would be nice.


For example, some time ago there were some examples in Color methods like
wheel: thisMany
"Return a collection of thisMany colors evenly spaced around the 
color wheel."

"Color showColors: (Color wheel: 12)"

the method #showColors: was long gone, so I replaced the comment to 
use #inspect instead.


But this code example is not about validation, a unit test would look like

self assert:(Color wheel: 12) equals: {(Color r: 0.7001 g: 
0.07 b: 0.07 alpha: 1.0). (Color r: 0.7001 .}


This code example is about a simple usage: "how would Color wheel:12 
look like ? Ha just inspect the result and see yourself"


And having a way to detect when the code example "Color showColors: 
.." doesn't work anymore because the method was

removed, or if the Code example
"(CompiledMethod compiledMethodAt: #author) author"
doesn't work anymore because the method was moved from CompiledMethod 
to Compiled code ;-)

would be nice.

Yes maybe we can find  another way to link real example code (not code 

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Nicolai Hess]

2016-09-19 10:33 GMT+02:00 Clément Bera :

> On Sat, Sep 17, 2016 at 8:18 AM, Tudor Girba  wrote:
>
>> Hi,
>>
>> > On Sep 16, 2016, at 8:37 PM, stepharo  wrote:
>> >
>> > + 1
>> >
>> > Changing the language metamodel for simple validated comments is a huge
>> effort for nothing.
>> > Clement is good at VM level but not at other level :)
>>
>> I think there is a misunderstanding :). I do not see any implication to
>> the language meta-model in the remark of Clement.
>>
>> In fact, I expressed exactly the same opinion, that the design of things
>> like PythonDoc comes from the fact that those people do not rely on an IDE,
>> so their design focuses on the only thing they have: source code. Clement
>> remarked that we already have SUnit tests and he suggested that we could
>> just enhance the IDE to present them next to the methods. This might
>> actually be less straightforward with SUnit because it was not made for
>> preserving links to the code, but it can work out of the box with something
>> like GTExamples.
>>
>
> Yes, the language meta-model is already too complex in Pharo IMHO, let's
> not make it even more complex. I should have precised that's not what I
> meant if this was not obvious to everyone.
>
> *1. Method docs with examples, so a user can see an example usage of a
> method (sunit test methods sometimes aren't good "examples")*
> *2. We already had (and still have) some method docs where the example
> code just won't work anymore because the methods or classes used*
>
> Nicolai,
>
> I'm suggesting to show the SUnit test code (or example code, or whatever)
> next to the method, and being able to create a unit test this way instead
> of only the existing green/red button and the "browse tests" entry in the
> right click menu. For existing methods having in their comment executable
> code to test how they work (as you mentioned), the code can just be moved
> to the test shown in the pane next to it (through a script discovering all
> cases like that or manually).
>
> The example usage would still be shown next to the code for the user,
> except it would already be under version control as existing SUnit tests
> are, it can now have syntax coloring which is not present in comments, it's
> automatically executed by each Pharo build through SUnit hence detecting
> regressions and the meta-model is not getting more complex at all. As Tudor
> said, it's only about IDE changes.
>
> I believe that some SUnit tests are sometimes not good examples because
> they're higher level tests (application tests, business tests) while as for
> python doctests it's only relevant to show unit tests next to the method
> the unit test validates. Currently I believe Nautilus discovers tests and
> add the green/red button based on name conventions. Foo>>bar has this
> feature if FooTests>>testBar is implemented. So it's either a matter of
> improving this heuristic or educating the community with this existing name
> convention. In any case, I don't think it's more changes for the user than
> having to learn convention in the comments/pragmas.
>
>
Yes, we should d some experiments with different solutions and see what
works.

I like the simplicity of having code in comments, at the moment I don't
like when we use the code highlighter, because this looks a bit confusing.

I would like a better link between methods and sunit tests, too.

I still don't think that unit tests can fully replace code examples. And
having a possibility to validate the code from method comments would be
nice.

For example, some time ago there were some examples in Color methods like
wheel: thisMany
"Return a collection of thisMany colors evenly spaced around the color
wheel."
"Color showColors: (Color wheel: 12)"

the method #showColors: was long gone, so I replaced the comment to use
#inspect instead.

But this code example is not about validation, a unit test would look like

self assert:(Color wheel: 12) equals: {(Color r: 0.7001 g: 0.07
b: 0.07 alpha: 1.0). (Color r: 0.7001 .}

This code example is about a simple usage: "how would Color wheel:12 look
like ? Ha just inspect the result and see yourself"

And having a way to detect when the code example "Color showColors: .."
doesn't work anymore because the method was
removed, or if the Code example
"(CompiledMethod compiledMethodAt: #author) author"
doesn't work anymore because the method was moved from CompiledMethod to
Compiled code ;-)
would be nice.

Yes maybe we can find  another way to link real example code (not code in
comments) to the actual method with better tool support, but we can not
cover this with unit tests style methods alone.

Even a simple example like:
'pharo' capitalized  " >>> 'Pharo'"
this reads better than
self assert:'pharo' capitalized equals:'Pharo'
Ok, it is not that bad to understand the usage of 'capitalized', its iput
and output from this unit test, but not all 

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Clément Bera]

On Sat, Sep 17, 2016 at 8:18 AM, Tudor Girba  wrote:

> Hi,
>
> > On Sep 16, 2016, at 8:37 PM, stepharo  wrote:
> >
> > + 1
> >
> > Changing the language metamodel for simple validated comments is a huge
> effort for nothing.
> > Clement is good at VM level but not at other level :)
>
> I think there is a misunderstanding :). I do not see any implication to
> the language meta-model in the remark of Clement.
>
> In fact, I expressed exactly the same opinion, that the design of things
> like PythonDoc comes from the fact that those people do not rely on an IDE,
> so their design focuses on the only thing they have: source code. Clement
> remarked that we already have SUnit tests and he suggested that we could
> just enhance the IDE to present them next to the methods. This might
> actually be less straightforward with SUnit because it was not made for
> preserving links to the code, but it can work out of the box with something
> like GTExamples.
>

Yes, the language meta-model is already too complex in Pharo IMHO, let's
not make it even more complex. I should have precised that's not what I
meant if this was not obvious to everyone.

*1. Method docs with examples, so a user can see an example usage of a
method (sunit test methods sometimes aren't good "examples")*
*2. We already had (and still have) some method docs where the example code
just won't work anymore because the methods or classes used*

Nicolai,

I'm suggesting to show the SUnit test code (or example code, or whatever)
next to the method, and being able to create a unit test this way instead
of only the existing green/red button and the "browse tests" entry in the
right click menu. For existing methods having in their comment executable
code to test how they work (as you mentioned), the code can just be moved
to the test shown in the pane next to it (through a script discovering all
cases like that or manually).

The example usage would still be shown next to the code for the user,
except it would already be under version control as existing SUnit tests
are, it can now have syntax coloring which is not present in comments, it's
automatically executed by each Pharo build through SUnit hence detecting
regressions and the meta-model is not getting more complex at all. As Tudor
said, it's only about IDE changes.

I believe that some SUnit tests are sometimes not good examples because
they're higher level tests (application tests, business tests) while as for
python doctests it's only relevant to show unit tests next to the method
the unit test validates. Currently I believe Nautilus discovers tests and
add the green/red button based on name conventions. Foo>>bar has this
feature if FooTests>>testBar is implemented. So it's either a matter of
improving this heuristic or educating the community with this existing name
convention. In any case, I don't think it's more changes for the user than
having to learn convention in the comments/pragmas.





> Cheers,
> Doru
>
>
> > Stef
> >
> > Le 16/9/16 à 14:18, Denis Kudriashov a écrit :
> >>
> >> 2016-09-16 13:42 GMT+02:00 Clément Bera :
> >> Why don't you just change nautilus to have two text areas, one with the
> test corresponding to the method and the other one with the method's code ?
> >>
> >> You're saying:
> >> Their values is active documentation that can be automatically
> validated.
> >> That can also be applied to test we've already had with SUnit. If the
> only difference you want is to display the test next to the method, then
> it's an IDE problem, nothing has to be changed but the IDE.
> >>
> >> In python they have no other choices than putting tests in comments
> because their IDE is a text editor, they cannot create other panes or
> anything like that.
> >>
> >> It is of course true. But Stef suggestion is really much much simpler.
> It is just convention how to write examples inside comments. Then tools
> could work with them and Nicolai already provide simple extension for
> Nautilus.
> >> We already has a lot of comments with examples inside. Making them
> discoverable and testable will be nice.
> >>
> >
>
> --
> www.tudorgirba.com
> www.feenk.com
>
> "Yesterday is a fact.
>  Tomorrow is a possibility.
>  Today is a challenge."
>
>
>
>
>
>

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Tudor Girba]

Hi,

> On Sep 16, 2016, at 8:37 PM, stepharo  wrote:
> 
> + 1
> 
> Changing the language metamodel for simple validated comments is a huge 
> effort for nothing. 
> Clement is good at VM level but not at other level :)

I think there is a misunderstanding :). I do not see any implication to the 
language meta-model in the remark of Clement.

In fact, I expressed exactly the same opinion, that the design of things like 
PythonDoc comes from the fact that those people do not rely on an IDE, so their 
design focuses on the only thing they have: source code. Clement remarked that 
we already have SUnit tests and he suggested that we could just enhance the IDE 
to present them next to the methods. This might actually be less 
straightforward with SUnit because it was not made for preserving links to the 
code, but it can work out of the box with something like GTExamples.

Cheers,
Doru


> Stef
> 
> Le 16/9/16 à 14:18, Denis Kudriashov a écrit :
>> 
>> 2016-09-16 13:42 GMT+02:00 Clément Bera :
>> Why don't you just change nautilus to have two text areas, one with the test 
>> corresponding to the method and the other one with the method's code ? 
>> 
>> You're saying:
>> Their values is active documentation that can be automatically validated.
>> That can also be applied to test we've already had with SUnit. If the only 
>> difference you want is to display the test next to the method, then it's an 
>> IDE problem, nothing has to be changed but the IDE.
>> 
>> In python they have no other choices than putting tests in comments because 
>> their IDE is a text editor, they cannot create other panes or anything like 
>> that.
>> 
>> It is of course true. But Stef suggestion is really much much simpler. It is 
>> just convention how to write examples inside comments. Then tools could work 
>> with them and Nicolai already provide simple extension for Nautilus.
>> We already has a lot of comments with examples inside. Making them 
>> discoverable and testable will be nice. 
>> 
> 

--
www.tudorgirba.com
www.feenk.com

"Yesterday is a fact.
 Tomorrow is a possibility.
 Today is a challenge."

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

Le 16/9/16 à 21:58, Damien Pollet a écrit :
On 16 September 2016 at 20:42, stepharo > wrote:


Daemons of over-engineering are tempting us because this is cooler
to to design something complex.


Dreaming of crazy features is a good thing. Talking from experience, I 
prefer that to not dreaming, which is pretty dull.


Yes now create a thread:
the dreams for a cool documentation system in Pharo and I will 
follow and add to it happily,
What I was asking in this thread is how can we catch a low hanging fruit 
and get an immmediate impact because it looks

so easy to do.

Stef


And over-engineering is of course the wrong path. But the temptation 
to do so is revealing of where the system is too complex.


--
Damien Pollet
type less, do more [ | ] http://people.untyped.org/damien.pollet

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Damien Pollet]

On 16 September 2016 at 20:42, stepharo  wrote:

> Daemons of over-engineering are tempting us because this is cooler to to
> design something complex.
>

Dreaming of crazy features is a good thing. Talking from experience, I
prefer that to not dreaming, which is pretty dull.

And over-engineering is of course the wrong path. But the temptation to do
so is revealing of where the system is too complex.

-- 
Damien Pollet
type less, do more [ | ] http://people.untyped.org/damien.pollet

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

Package level doc is quite useful to outline how some things are
working together, something which is quite hard to figure out
except by reading external doc or inferring things by walking
through the code or a running test.



Why don't we have yet package comments ?


Just because we are too busy.
I see there is some support for it in PackageManifest, I remember 
there was some work (people working) on support for Nautilus, no?

Christophe is working on the manifest to support cargo metadata.


maybe something like this, (see attached file)
Nautilus comment pane
on class selection -> show class comment
no class selection -> show package comment (class side #description of 
package manifest of this package)
you can even add or change the (package) comment, it will compile a 
proper #description method on the manifest class)


Yes this is one idea. I would love to have package comment.






Having the ability to read about a package would be very useful.
Basically, this is what Java provides.


http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#packagecomment



Phil


On Thu, Sep 15, 2016 at 8:45 PM, stepharo > wrote:

Hi all

I want something similar in the spirit to PythonDocTest
https://docs.python.org/2/library/doctest.html


I'm talking about

basename
"Returns the base of the basename,
i.e.
/foo/gloops.taz basename is 'gloops.taz'
/ basename is '/'"

Pragmas do not work well i.e.,
basename
"Returns the base of the basename"
 


We should invent a syntax to be put inside comments and that
we can easily parse because we need to improve
the use and discovery of the library.

I was thinking about

basename
"Returns the base of the basename"
"
'/foo/gloops.taz' asFileReference basename
>>> 'gloops.taz'
"

Do you have any idea?

I cannot not do anything and just complain that our methods
are not that well documented.
We as a community should take this and build an super cool system.

I tried and defined >>> on Object to see if it works!

Object >>> aResultingObject
"If the method comment contains >>> then it is a pharo
documentated test. We can check that it is true."

"
'/foo/gloops.taz' asFileReference basename
   >>> 'gloops.taz'
"

^ self = aResultingObject


Stef

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

Le 16/9/16 à 15:26, Damien Pollet a écrit :
On 16 September 2016 at 13:42, Clément Bera > wrote:


Why don't you just change nautilus to have two text areas, one
with the test corresponding to the method and the other one with
the method's code ? 



Exactly, we already have that with class comments, so why not methods 
(and while we're at it, package comments too)


I love you guys.
Let us change MCZ binary storage, pharo language metamodel and more 
while we are at it.

Not talking about merging and others.

Sorry there is a huge tradeoffs with simplicity and gain.
And you are just jumping into building a monster for ONE LINERS

Repeat after me ONE LINERS.

I prefer to keep my energy for worth large enhancements and grab low 
hanging fruits when I see them.
And Nicolai showed it to us. We cn get some variation and get all the 
easy benefits.


Daemons of over-engineering are tempting us because this is cooler to to 
design something complex.

But KISS to the rescue.
Stef


A separate method comment would make it clear that it's intended as 
API documentation for users of the method (and then the comment inside 
the method's source can be really a development comment). Another 
advantage is that its syntax won't have to deal with being between 
quotes and all the indentation/escapement hassles that come with 
inserting a syntax inside another one…


--
Damien Pollet
type less, do more [ | ] http://people.untyped.org/damien.pollet

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

This is what I thought first, we already have the association between 
methods and tests, Nautilus can detect if there
is a corresponding test , for example browse Fraction>>truncated, it 
will show a test icon, that will run the test 
FractionTest>>#testTruncated.
This works already good, and I think we don't need special comments or 
pragmas for this.


But what stef wants is
1. Method docs with examples, so a user can see an example usage of a 
method (sunit test methods sometimes aren't good "examples")
2. We already had (and still have) some method docs where the example 
code just won't work anymore because the methods or classes used
 by the example were removed, renamed. So, it would be good if we can 
extract these examples and run them automatically to make sure they

are still working.

But yes, maybe we can still solve this with better Tools, not working 
only on the plain text in comments.


This can be done in addition but first we should be able to encode them.

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

+ 1

Changing the language metamodel for simple validated comments is a huge 
effort for nothing.


Clement is good at VM level but not at other level :)

Stef

Le 16/9/16 à 14:18, Denis Kudriashov a écrit :


2016-09-16 13:42 GMT+02:00 Clément Bera >:


Why don't you just change nautilus to have two text areas, one
with the test corresponding to the method and the other one with
the method's code ?

You're saying:
/Their values is active documentation that can be automatically
validated./
That can also be applied to test we've already had with SUnit. If
the only difference you want is to display the test next to the
method, then it's an IDE problem, nothing has to be changed but
the IDE.

In python they have no other choices than putting tests in
comments because their IDE is a text editor, they cannot create
other panes or anything like that.


It is of course true. But Stef suggestion is really much much simpler. 
It is just convention how to write examples inside comments. Then 
tools could work with them and Nicolai already provide simple 
extension for Nautilus.
We already has a lot of comments with examples inside. Making them 
discoverable and testable will be nice.

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

Le 16/9/16 à 13:42, Clément Bera a écrit :
Why don't you just change nautilus to have two text areas, one with 
the test corresponding to the method and the other one with the 
method's code ?


You're saying:
/Their values is active documentation that can be automatically 
validated./
That can also be applied to test we've already had with SUnit. If the 
only difference you want is to display the test next to the method, 
then it's an IDE problem, nothing has to be changed but the IDE.


and you want to create different semantic objects... well you 
underestimate the amount of work.
Ask pavel just to get a semantically model for Pharo just plain pharo 
with Slot and Traits.


Stef


In python they have no other choices than putting tests in comments 
because their IDE is a text editor, they cannot create other panes or 
anything like that.


Clement how do you save/store/merge
in a method it is cheap and working.


On Fri, Sep 16, 2016 at 1:21 PM, stepharo > 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'
"



We could have for class comment

">>>UMLDescription
UMLClass named: 'Visitor'

Arrow from:

But this can start to be complex
"


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.

I do not know because all the comments should be pillar compatible.
If you do not use pillar commands you just get plain text.
You see we can easily detect comment too: if a text contains >>>
then it is a doc

Then
ExampleDoc
is an extra syntax.

I'm not found with the
self assert:
because it feels like something coming out of nowhere. We will
have to explain: yes self is bound to an instance of the testCase...
and to me this is implementation details:
if I give expr1 and expr2 the implementation can build self
assert: expr1 equals: expr2

I liked the simplicity of nicolai' solution
I would just have a comment and a message >>> so that we
=> nearly no syntax change
=> something really lightweight and optional


What I care is that

- we get simple examples right in the method
- one line no more.
- that these examples are correct and always validated (I do
not see them as tests), their values is more in the correct
documentation
than the tests. They are basic output. I do not want to have
full code in the method, in that case this should go one class
side example
or plain tests.



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.

I do not think that expressions can fit inside pragmas

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

To me I do not care that they are tests.
Their values is active documentation that can be automatically
validated. I do not expect to run them but the system
can garantee that they are correct.


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 

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

Hi

2016-09-16 13:21 GMT+02:00 stepharo >:



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

To me I do not care that they are tests.
Their values is active documentation that can be automatically
validated. I do not expect to run them but the system
can garantee that they are correct. 



How it could work? Somebody need to press button to check all comments 
are valid. No?


the integration run the validation and says that system documentation is ok.
We do that all the time with Quqlity rules.

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[philippe.b...@highoctane.be]

How is all of this PackageManifest mechanism working?

Doc anywhere?

Phil

Le 16 sept. 2016 17:02, "Nicolai Hess"  a écrit :



2016-09-16 0:19 GMT+02:00 p...@highoctane.be :

> I'd be more interested with a package level doc than a class doc or test.
>
> Package level doc is quite useful to outline how some things are working
> together, something which is quite hard to figure out except by reading
> external doc or inferring things by walking through the code or a running
> test.
>


Why don't we have yet package comments ?
I see there is some support for it in PackageManifest, I remember there was
some work (people working) on support for Nautilus, no?

maybe something like this, (see attached file)
Nautilus comment pane
on class selection -> show class comment
no class selection -> show package comment (class side #description of
package manifest of this package)
you can even add or change the (package) comment, it will compile a proper
#description method on the manifest class)




>
> Having the ability to read about a package would be very useful.
> Basically, this is what Java provides.
>
> http://docs.oracle.com/javase/7/docs/technotes/tools/solaris
> /javadoc.html#packagecomment
>
> Phil
>
>
> On Thu, Sep 15, 2016 at 8:45 PM, stepharo  wrote:
>
>> Hi all
>>
>> I want something similar in the spirit to PythonDocTest
>> https://docs.python.org/2/library/doctest.html
>>
>> I'm talking about
>>
>> basename
>> "Returns the base of the basename,
>> i.e.
>> /foo/gloops.taz basename is 'gloops.taz'
>> / basename is '/'"
>>
>> Pragmas do not work well i.e.,
>> basename
>> "Returns the base of the basename"
>>  > 'gloops.taz'>
>>
>>
>> We should invent a syntax to be put inside comments and that we can
>> easily parse because we need to improve
>> the use and discovery of the library.
>>
>> I was thinking about
>>
>> basename
>> "Returns the base of the basename"
>> "
>> '/foo/gloops.taz' asFileReference basename
>> >>> 'gloops.taz'
>> "
>>
>> Do you have any idea?
>>
>> I cannot not do anything and just complain that our methods are not that
>> well documented.
>> We as a community should take this and build an super cool system.
>>
>> I tried and defined >>> on Object to see if it works!
>>
>> Object >>> aResultingObject
>> "If the method comment contains >>> then it is a pharo documentated
>> test. We can check that it is true."
>>
>> "
>> '/foo/gloops.taz' asFileReference basename
>>>>> 'gloops.taz'
>> "
>>
>> ^ self = aResultingObject
>>
>>
>> Stef
>>
>>
>>
>

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Nicolai Hess]

2016-09-16 0:19 GMT+02:00 p...@highoctane.be :

> I'd be more interested with a package level doc than a class doc or test.
>
> Package level doc is quite useful to outline how some things are working
> together, something which is quite hard to figure out except by reading
> external doc or inferring things by walking through the code or a running
> test.
>


Why don't we have yet package comments ?
I see there is some support for it in PackageManifest, I remember there was
some work (people working) on support for Nautilus, no?

maybe something like this, (see attached file)
Nautilus comment pane
on class selection -> show class comment
no class selection -> show package comment (class side #description of
package manifest of this package)
you can even add or change the (package) comment, it will compile a proper
#description method on the manifest class)




>
> Having the ability to read about a package would be very useful.
> Basically, this is what Java provides.
>
> http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#
> packagecomment
>
> Phil
>
>
> On Thu, Sep 15, 2016 at 8:45 PM, stepharo  wrote:
>
>> Hi all
>>
>> I want something similar in the spirit to PythonDocTest
>> https://docs.python.org/2/library/doctest.html
>>
>> I'm talking about
>>
>> basename
>> "Returns the base of the basename,
>> i.e.
>> /foo/gloops.taz basename is 'gloops.taz'
>> / basename is '/'"
>>
>> Pragmas do not work well i.e.,
>> basename
>> "Returns the base of the basename"
>>  > 'gloops.taz'>
>>
>>
>> We should invent a syntax to be put inside comments and that we can
>> easily parse because we need to improve
>> the use and discovery of the library.
>>
>> I was thinking about
>>
>> basename
>> "Returns the base of the basename"
>> "
>> '/foo/gloops.taz' asFileReference basename
>> >>> 'gloops.taz'
>> "
>>
>> Do you have any idea?
>>
>> I cannot not do anything and just complain that our methods are not that
>> well documented.
>> We as a community should take this and build an super cool system.
>>
>> I tried and defined >>> on Object to see if it works!
>>
>> Object >>> aResultingObject
>> "If the method comment contains >>> then it is a pharo documentated
>> test. We can check that it is true."
>>
>> "
>> '/foo/gloops.taz' asFileReference basename
>>>>> 'gloops.taz'
>> "
>>
>> ^ self = aResultingObject
>>
>>
>> Stef
>>
>>
>>
>


package_comment.cs
Description: Binary data

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Thierry Goubier]

Sorry for the mistake,

2016-09-16 15:51 GMT+02:00 Damien Pollet :

> On 16 September 2016 at 15:35, Thierry Goubier 
> wrote:
>
>> Could we have a Pillar-way of organizing comments so that, based on
>> sections, one could automatically find, from a book-like comment of the
>> package or the class, which section applies to a given method?
>
>
> I guess it's like any cross-referencing or indexing system… I'm guessing a
> purely automatic system would find irrelevant matches and miss related
> stuff, so it would need some human-added hints. But no one can reasonably
> go through the cross-product of docs and code, adding hints, so that would
> need to be crowdsourced and aggregated, a bit like the QA critiques.
>

If one could reference the package code (class / method) as a reference
inside the Pillar comment, would that work? I'm a bit wary of an
'automatic' approach, but I'd find great to go in a fluid way from text to
code and back.

For those who remember, my idea would be like referencing chapters and
sections of the LaTeX generation of smalltalk source code... If you
reference {\ref aClass:aProtocol:aMethod} then you get a live two-way link
between the comment and the code in the browser.


> I'll leave this link to the Django docs: https://docs.
> djangoproject.com/en/1.10/
> I recently watched a talk from I think the Django lead who was explaining
> the different kinds of docs (tutorials, howtos, topic guides, and
> reference). Package/class/method comments would be reference doc, but would
> need to cross-ref with any other docs too…
>

I'd make it simple: start with a book-like document cross-referenced with
the live code, as the preferred documentation for a package.

Thierry


>
>
> --
> Damien Pollet
> type less, do more [ | ] http://people.untyped.org/damien.pollet
>

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Thierry Goubier]

2016-09-16 15:51 GMT+02:00 Damien Pollet :

> On 16 September 2016 at 15:35, Thierry Goubier 
> wrote:
>
>> Could we have a Pillar-way of organizing comments so that, based on
>> sections, one could automatically find, from a book-like comment of the
>> package or the class, which section applies to a given method?
>
>
> I guess it's like any cross-referencing or indexing system… I'm guessing a
> purely automatic system would find irrelevant matches and miss related
> stuff, so it would need some human-added hints. But no one can reasonably
> go through the cross-product of docs and code, adding hints, so that would
> need to be crowdsourced and aggregated, a bit like the QA critiques.
>

If one could, in a Pillar doc of a package, unify the packa


>
> I'll leave this link to the Django docs: https://docs.
> djangoproject.com/en/1.10/
> I recently watched a talk from I think the Django lead who was explaining
> the different kinds of docs (tutorials, howtos, topic guides, and
> reference). Package/class/method comments would be reference doc, but would
> need to cross-ref with any other docs too…
>
> --
> Damien Pollet
> type less, do more [ | ] http://people.untyped.org/damien.pollet
>

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Bernardo Ezequiel Contreras]

Another example:
https://docs.racket-lang.org/scribble/index.html

First example:
https://docs.racket-lang.org/scribble/getting-started.html#%28part._first-example%29


On Fri, Sep 16, 2016 at 10:51 AM, Damien Pollet 
wrote:

> On 16 September 2016 at 15:35, Thierry Goubier 
> wrote:
>
>> Could we have a Pillar-way of organizing comments so that, based on
>> sections, one could automatically find, from a book-like comment of the
>> package or the class, which section applies to a given method?
>
>
> I guess it's like any cross-referencing or indexing system… I'm guessing a
> purely automatic system would find irrelevant matches and miss related
> stuff, so it would need some human-added hints. But no one can reasonably
> go through the cross-product of docs and code, adding hints, so that would
> need to be crowdsourced and aggregated, a bit like the QA critiques.
>
> I'll leave this link to the Django docs: https://docs.
> djangoproject.com/en/1.10/
> I recently watched a talk from I think the Django lead who was explaining
> the different kinds of docs (tutorials, howtos, topic guides, and
> reference). Package/class/method comments would be reference doc, but would
> need to cross-ref with any other docs too…
>
> --
> Damien Pollet
> type less, do more [ | ] http://people.untyped.org/damien.pollet
>



-- 
Bernardo E.C.

Sent from a cheap desktop computer in South America.

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Damien Pollet]

On 16 September 2016 at 15:35, Thierry Goubier 
wrote:

> Could we have a Pillar-way of organizing comments so that, based on
> sections, one could automatically find, from a book-like comment of the
> package or the class, which section applies to a given method?


I guess it's like any cross-referencing or indexing system… I'm guessing a
purely automatic system would find irrelevant matches and miss related
stuff, so it would need some human-added hints. But no one can reasonably
go through the cross-product of docs and code, adding hints, so that would
need to be crowdsourced and aggregated, a bit like the QA critiques.

I'll leave this link to the Django docs:
https://docs.djangoproject.com/en/1.10/
I recently watched a talk from I think the Django lead who was explaining
the different kinds of docs (tutorials, howtos, topic guides, and
reference). Package/class/method comments would be reference doc, but would
need to cross-ref with any other docs too…

-- 
Damien Pollet
type less, do more [ | ] http://people.untyped.org/damien.pollet

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Thierry Goubier]

2016-09-16 15:26 GMT+02:00 Damien Pollet :

> On 16 September 2016 at 13:42, Clément Bera 
> wrote:
>
>> Why don't you just change nautilus to have two text areas, one with the
>> test corresponding to the method and the other one with the method's code ?
>
>
> Exactly, we already have that with class comments, so why not methods (and
> while we're at it, package comments too)
>

Could we have a Pillar-way of organizing comments so that, based on
sections, one could automatically find, from a book-like comment of the
package or the class, which section applies to a given method?


>
> A separate method comment would make it clear that it's intended as API
> documentation for users of the method (and then the comment inside the
> method's source can be really a development comment). Another advantage is
> that its syntax won't have to deal with being between quotes and all the
> indentation/escapement hassles that come with inserting a syntax inside
> another one…
>

Good point.

Thierry


>
> --
> Damien Pollet
> type less, do more [ | ] http://people.untyped.org/damien.pollet
>

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Damien Pollet]

On 16 September 2016 at 13:42, Clément Bera  wrote:

> Why don't you just change nautilus to have two text areas, one with the
> test corresponding to the method and the other one with the method's code ?


Exactly, we already have that with class comments, so why not methods (and
while we're at it, package comments too)

A separate method comment would make it clear that it's intended as API
documentation for users of the method (and then the comment inside the
method's source can be really a development comment). Another advantage is
that its syntax won't have to deal with being between quotes and all the
indentation/escapement hassles that come with inserting a syntax inside
another one…

-- 
Damien Pollet
type less, do more [ | ] http://people.untyped.org/damien.pollet

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Thierry Goubier]

2016-09-16 14:25 GMT+02:00 Nicolai Hess :

>
>
> 2016-09-16 13:42 GMT+02:00 Clément Bera :
>
>> Why don't you just change nautilus to have two text areas, one with the
>> test corresponding to the method and the other one with the method's code ?
>>
>> You're saying:
>> *Their values is active documentation that can be automatically
>> validated.*
>> That can also be applied to test we've already had with SUnit. If the
>> only difference you want is to display the test next to the method, then
>> it's an IDE problem, nothing has to be changed but the IDE.
>>
>
> This is what I thought first, we already have the association between
> methods and tests, Nautilus can detect if there
> is a corresponding test , for example browse Fraction>>truncated, it will
> show a test icon, that will run the test FractionTest>>#testTruncated.
> This works already good, and I think we don't need special comments or
> pragmas for this.
>
> But what stef wants is
> 1. Method docs with examples, so a user can see an example usage of a
> method (sunit test methods sometimes aren't good "examples")
>

I'd prefer to have a Pillar doc for my class / package / project with live
code portions, with a link method to chapter. We use examples inside
comments because we don't have anything better...


> 2. We already had (and still have) some method docs where the example code
> just won't work anymore because the methods or classes used
>  by the example were removed, renamed. So, it would be good if we can
> extract these examples and run them automatically to make sure they
> are still working.
>

This one is independant of the syntax. If they are in, say, the Pillar
description of the class, of course they can be tested and run everytime we
save a new version of the package ? Or as a test case?

What about examples that create views, windows and external files? How do
we test they are still valid without making those a sunit test with a
teardown?


>
> But yes, maybe we can still solve this with better Tools, not working only
> on the plain text in comments.
>

Exactly. Moreover given what we're focusing on with GT.

Thierry

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Nicolai Hess]

2016-09-16 13:42 GMT+02:00 Clément Bera :

> Why don't you just change nautilus to have two text areas, one with the
> test corresponding to the method and the other one with the method's code ?
>
> You're saying:
> *Their values is active documentation that can be automatically validated.*
> That can also be applied to test we've already had with SUnit. If the only
> difference you want is to display the test next to the method, then it's an
> IDE problem, nothing has to be changed but the IDE.
>

This is what I thought first, we already have the association between
methods and tests, Nautilus can detect if there
is a corresponding test , for example browse Fraction>>truncated, it will
show a test icon, that will run the test FractionTest>>#testTruncated.
This works already good, and I think we don't need special comments or
pragmas for this.

But what stef wants is
1. Method docs with examples, so a user can see an example usage of a
method (sunit test methods sometimes aren't good "examples")
2. We already had (and still have) some method docs where the example code
just won't work anymore because the methods or classes used
 by the example were removed, renamed. So, it would be good if we can
extract these examples and run them automatically to make sure they
are still working.

But yes, maybe we can still solve this with better Tools, not working only
on the plain text in comments.


>
> In python they have no other choices than putting tests in comments
> because their IDE is a text editor, they cannot create other panes or
> anything like that.
>
> On Fri, Sep 16, 2016 at 1:21 PM, stepharo  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'
>> "
>>
>>
>> We could have for class comment
>>
>> ">>>UMLDescription
>> UMLClass named: 'Visitor'
>>
>> Arrow from:
>>
>> But this can start to be complex
>> "
>>
>> 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.
>>
>> I do not know because all the comments should be pillar compatible.
>> If you do not use pillar commands you just get plain text.
>> You see we can easily detect comment too: if a text contains >>> then it
>> is a doc
>>
>> Then
>> ExampleDoc
>> is an extra syntax.
>>
>> I'm not found with the
>> self assert:
>> because it feels like something coming out of nowhere. We will have to
>> explain: yes self is bound to an instance of the testCase...
>> and to me this is implementation details:
>> if I give expr1 and expr2 the implementation can build self assert:
>> expr1 equals: expr2
>>
>> I liked the simplicity of nicolai' solution
>> I would just have a comment and a message >>> so that we
>> => nearly no syntax change
>> => something really lightweight and optional
>>
>>
>> What I care is that
>>
>> - we get simple examples right in the method
>> - one line no more.
>> - that these examples are correct and always validated (I do not see
>> them as tests), their values is more in the correct documentation
>> than the tests. They are basic output. I do not want to have full
>> code in the method, in that case this should go one class side example
>> or plain tests.
>>
>>
>> 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.
>>
>> I do not think that expressions can fit inside pragmas
>>
>>   - there is an overlap between examples and test cases. I saw many
>> people 

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Denis Kudriashov]

2016-09-16 13:42 GMT+02:00 Clément Bera :

> Why don't you just change nautilus to have two text areas, one with the
> test corresponding to the method and the other one with the method's code ?
>
> You're saying:
> *Their values is active documentation that can be automatically validated.*
> That can also be applied to test we've already had with SUnit. If the only
> difference you want is to display the test next to the method, then it's an
> IDE problem, nothing has to be changed but the IDE.
>
> In python they have no other choices than putting tests in comments
> because their IDE is a text editor, they cannot create other panes or
> anything like that.
>

It is of course true. But Stef suggestion is really much much simpler. It
is just convention how to write examples inside comments. Then tools could
work with them and Nicolai already provide simple extension for Nautilus.
We already has a lot of comments with examples inside. Making them
discoverable and testable will be nice.

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Clément Bera]

Why don't you just change nautilus to have two text areas, one with the
test corresponding to the method and the other one with the method's code ?

You're saying:
*Their values is active documentation that can be automatically validated.*
That can also be applied to test we've already had with SUnit. If the only
difference you want is to display the test next to the method, then it's an
IDE problem, nothing has to be changed but the IDE.

In python they have no other choices than putting tests in comments because
their IDE is a text editor, they cannot create other panes or anything like
that.

On Fri, Sep 16, 2016 at 1:21 PM, stepharo  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'
> "
>
>
> We could have for class comment
>
> ">>>UMLDescription
> UMLClass named: 'Visitor'
>
> Arrow from:
>
> But this can start to be complex
> "
>
> 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.
>
> I do not know because all the comments should be pillar compatible.
> If you do not use pillar commands you just get plain text.
> You see we can easily detect comment too: if a text contains >>> then it
> is a doc
>
> Then
> ExampleDoc
> is an extra syntax.
>
> I'm not found with the
> self assert:
> because it feels like something coming out of nowhere. We will have to
> explain: yes self is bound to an instance of the testCase...
> and to me this is implementation details:
> if I give expr1 and expr2 the implementation can build self assert:
> expr1 equals: expr2
>
> I liked the simplicity of nicolai' solution
> I would just have a comment and a message >>> so that we
> => nearly no syntax change
> => something really lightweight and optional
>
>
> What I care is that
>
> - we get simple examples right in the method
> - one line no more.
> - that these examples are correct and always validated (I do not see
> them as tests), their values is more in the correct documentation
> than the tests. They are basic output. I do not want to have full code
> in the method, in that case this should go one class side example
> or plain tests.
>
>
> 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.
>
> I do not think that expressions can fit inside pragmas
>
>   - 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.
>
> To me I do not care that they are tests.
> Their values is active documentation that can be automatically validated.
> I do not expect to run them but the system
> can garantee that they are correct.
>
> 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?)
>
> I do not get what you mean here.
>
> For me a test is a scenario.
> If I do that and that then this happens
> a test can use a class example
>
> Now for me a test should not rely one a online part of method comment.
>
> These onliners are just make the method comments better.
>
>
>
>
>
> Guille
>
>  Original Message 
>
> Hi nicolai
>
>
> I was thinking that I would prefer to have
>
>
> "` '/foo/gloops.taz' asFileReference basename -> 'gloops.taz'.`"
>
>
> instead of

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Denis Kudriashov]

Hi

2016-09-16 13:21 GMT+02:00 stepharo :

>   - 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.
>
> To me I do not care that they are tests.
> Their values is active documentation that can be automatically validated.
> I do not expect to run them but the system
> can garantee that they are correct.


How it could work? Somebody need to press button to check all comments are
valid. No?

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

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'

"



We could have for class comment

">>>UMLDescription
UMLClass named: 'Visitor'

Arrow from:

But this can start to be complex
"


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.

I do not know because all the comments should be pillar compatible.
If you do not use pillar commands you just get plain text.
You see we can easily detect comment too: if a text contains >>> then it 
is a doc


Then
ExampleDoc
is an extra syntax.

I'm not found with the
self assert:
because it feels like something coming out of nowhere. We will have to 
explain: yes self is bound to an instance of the testCase...

and to me this is implementation details:
if I give expr1 and expr2 the implementation can build self assert: 
expr1 equals: expr2


I liked the simplicity of nicolai' solution
I would just have a comment and a message >>> so that we
=> nearly no syntax change
=> something really lightweight and optional


What I care is that

- we get simple examples right in the method
- one line no more.
- that these examples are correct and always validated (I do not 
see them as tests), their values is more in the correct documentation
than the tests. They are basic output. I do not want to have full 
code in the method, in that case this should go one class side example

or plain tests.



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.

I do not think that expressions can fit inside pragmas
  - 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.

To me I do not care that they are tests.
Their values is active documentation that can be automatically 
validated. I do not expect to run them but the system

can garantee that they are correct.

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

I do not get what you mean here.

For me a test is a scenario.
If I do that and that then this happens
a test can use a class example

Now for me a test should not rely one a online part of method comment.

These onliners are just make the method comments better.






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, 

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Esteban Lorenzano]

> On 16 Sep 2016, at 10:02, Guille Polito  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
>>> 
>>> 
>>> 
>> 
> 

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Serge Stinckwich]

On Thu, Sep 15, 2016 at 10:09 PM, Tudor Girba  wrote:
> Hi,
>
> I think this is an interesting idea.
>
> However, one thing to keep in mind is that one reason why these solutions 
> exist is because they assume no UI environment. Thus, the only thing they 
> have is text and the solution is built around it.
>
> In Pharo, we can think of concatenating information in the environment. If we 
> have a casual connection between examples and the code they exemplify, the 
> interface can provide all this information at the same time. The advantage 
> here is that the syntax remains simple.
>
> At the same time, we also want to have Pillar more thoroughly supported in 
> our tools. Could it be that we could extend Pillar to support literate 
> programming?

Just I backup this idea. You should have a look to http://orgmode.org/
with babel mode that allows to mix different programming languages in
the same document: http://orgmode.org/worg/org-contrib/babel/

Lot of ideas should be borrowed for doing a better Pillar I guess.
The only problem of org-mode is that you don't have the link to the
live environment that we are used to.
Having a org-mode clone in Pharo (i.e Pillar+++) would be great.

At the same time, this is a long term solution.
We also need an immediate solution like the one proposed by Stéphane.

Regards,
-- 
Serge Stinckwich
UCBN & UMI UMMISCO 209 (IRD/UPMC)
Every DSL ends up being Smalltalk
http://www.doesnotunderstand.org/

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Guille Polito]

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

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

I will play with it :)

I was thinking to have >>> instead of association to make sure that we 
can disambiguate from ->


Thanks for the protoype.

This kind of little action can change completely the face of Pharo 
library. I always ***LOVED*** little examples inside method


when I discovered Smalltalk.

This plus examples at the class side and link with nautilus execution -> 
gt inspector will really improve the situation.


Stef



Le 15/9/16 à 22:35, Nicolai Hess a écrit :



2016-09-15 20:45 GMT+02:00 stepharo >:


Hi all

I want something similar in the spirit to PythonDocTest
https://docs.python.org/2/library/doctest.html


I'm talking about

basename
"Returns the base of the basename,
i.e.
/foo/gloops.taz basename is 'gloops.taz'
/ basename is '/'"

Pragmas do not work well i.e.,
basename
"Returns the base of the basename"
 


We should invent a syntax to be put inside comments and that we
can easily parse because we need to improve
the use and discovery of the library.

I was thinking about

basename
"Returns the base of the basename"
"
'/foo/gloops.taz' asFileReference basename
>>> 'gloops.taz'
"

Do you have any idea?

I cannot not do anything and just complain that our methods are
not that well documented.
We as a community should take this and build an super cool system.

I tried and defined >>> on Object to see if it works!

Object >>> aResultingObject
"If the method comment contains >>> then it is a pharo
documentated test. We can check that it is true."

"
'/foo/gloops.taz' asFileReference basename
   >>> 'gloops.taz'
"

^ self = aResultingObject


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

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

Le 16/9/16 à 00:19, p...@highoctane.be a écrit :

I'd be more interested with a package level doc than a class doc or test.

It is at another level and it will come.
The manisfest is here and we should update Nautilus to show other 
information.


Now I'm curious to see how many people will use that when I see the 
level of description in configuration of.



Package level doc is quite useful to outline how some things are 
working together, something which is quite hard to figure out except 
by reading external doc or inferring things by walking through the 
code or a running test.


I'm the guy that propose SmallUML to embed description of UML diagram as 
package level 5 years ago and before that I tried

to add png of diagram so I'm convinced about that.


Having the ability to read about a package would be very useful. 
Basically, this is what Java provides.


http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#packagecomment

Phil


On Thu, Sep 15, 2016 at 8:45 PM, stepharo > wrote:


Hi all

I want something similar in the spirit to PythonDocTest
https://docs.python.org/2/library/doctest.html


I'm talking about

basename
"Returns the base of the basename,
i.e.
/foo/gloops.taz basename is 'gloops.taz'
/ basename is '/'"

Pragmas do not work well i.e.,
basename
"Returns the base of the basename"
 


We should invent a syntax to be put inside comments and that we
can easily parse because we need to improve
the use and discovery of the library.

I was thinking about

basename
"Returns the base of the basename"
"
'/foo/gloops.taz' asFileReference basename
>>> 'gloops.taz'
"

Do you have any idea?

I cannot not do anything and just complain that our methods are
not that well documented.
We as a community should take this and build an super cool system.

I tried and defined >>> on Object to see if it works!

Object >>> aResultingObject
"If the method comment contains >>> then it is a pharo
documentated test. We can check that it is true."

"
'/foo/gloops.taz' asFileReference basename
   >>> 'gloops.taz'
"

^ self = aResultingObject


Stef

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

Le 15/9/16 à 22:16, Esteban A. Maringolo a écrit :

2016-09-15 17:09 GMT-03:00 Tudor Girba :

However, one thing to keep in mind is that one reason why these solutions exist 
is because they assume no UI environment. Thus, the only thing they have is 
text and the solution is built around it.

In Pharo, we can think of concatenating information in the environment. If we 
have a casual connection between examples and the code they exemplify, the 
interface can provide all this information at the same time. The advantage here 
is that the syntax remains simple.

+1

I wouldn't like that syntax, nor PharoDoc (a la JavaDoc), nor anything
"polluting" the code that way.


It is not polution, it is documentation.
Apparently you are not the guy that got the HUGE pain to write the 
method comment and the chapter about FileSystem.
I'm probably too stupid. To understand what each method was doing I had 
to TRY and ERROR.
I recently try to understand certain behavior of the Date package and 
same syndrome. Without an example it is impossible to

get **exactly** what the method is doing.

So that you do not use it in your code is your style and life. Now Pharo 
must improve from that perspective.
I do not want to read five methods with different context to understand 
that basename includes the extension


 '/foo/gloops.taz' asFileReference basename is 'gloops.taz

and that name does not.

Sorry but as one of the leader of Pharo if I do not have such exigence 
and vision for our system then I should go do something else.


Stef



The comment or examples can be attributes of the method itself, just
like the class comment are today.

Regards!

Esteban A. Maringolo

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

On Fri, Sep 16, 2016 at 2:45 AM, stepharo  wrote:

Hi all

I want something similar in the spirit to PythonDocTest
https://docs.python.org/2/library/doctest.html

I'm talking about

basename
 "Returns the base of the basename,
 i.e.
 /foo/gloops.taz basename is 'gloops.taz'
 / basename is '/'"

Pragmas do not work well i.e.,
basename
 "Returns the base of the basename"
  


We should invent a syntax to be put inside comments and that we can easily
parse because we need to improve
the use and discovery of the library.

I was thinking about

basename
 "Returns the base of the basename"
 "
 '/foo/gloops.taz' asFileReference basename
 >>> 'gloops.taz'
 "

Do you have any idea?

basename
  "Returns the base of the basename"
  """
  '/foo/gloops.taz' asFileReference basename
 ==> 'gloops.taz'
  """
 self size == 0
 "the root node"
 ifTrue: [ ^ '/'].
  ^ self at: self size

I like this idea.  But a fine semantic
We should think of these less as "tests"
and more as "howto" snippets that are tested for correctness.

They should show just the *simplest* was to get an object to which the
method can be sent.
Maybe they could be also displayed via the gtExample interface ??


May be. Right now I want to make sure that all the little examples that 
are written for example

inside methods are correct.

Stef


cheers -ben

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Ben Coman]

On Fri, Sep 16, 2016 at 2:45 AM, stepharo  wrote:
> Hi all
>
> I want something similar in the spirit to PythonDocTest
> https://docs.python.org/2/library/doctest.html
>
> I'm talking about
>
> basename
> "Returns the base of the basename,
> i.e.
> /foo/gloops.taz basename is 'gloops.taz'
> / basename is '/'"
>
> Pragmas do not work well i.e.,
> basename
> "Returns the base of the basename"
>   'gloops.taz'>
>
>
> We should invent a syntax to be put inside comments and that we can easily
> parse because we need to improve
> the use and discovery of the library.
>
> I was thinking about
>
> basename
> "Returns the base of the basename"
> "
> '/foo/gloops.taz' asFileReference basename
> >>> 'gloops.taz'
> "
>
> Do you have any idea?

basename
 "Returns the base of the basename"
 """
 '/foo/gloops.taz' asFileReference basename
==> 'gloops.taz'
 """
self size == 0
"the root node"
ifTrue: [ ^ '/'].
 ^ self at: self size

I like this idea.  But a fine semantic
We should think of these less as "tests"
and more as "howto" snippets that are tested for correctness.

They should show just the *simplest* was to get an object to which the
method can be sent.
Maybe they could be also displayed via the gtExample interface ??

cheers -ben

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[p...@highoctane.be]

I'd be more interested with a package level doc than a class doc or test.

Package level doc is quite useful to outline how some things are working
together, something which is quite hard to figure out except by reading
external doc or inferring things by walking through the code or a running
test.

Having the ability to read about a package would be very useful. Basically,
this is what Java provides.

http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#packagecomment

Phil


On Thu, Sep 15, 2016 at 8:45 PM, stepharo  wrote:

> Hi all
>
> I want something similar in the spirit to PythonDocTest
> https://docs.python.org/2/library/doctest.html
>
> I'm talking about
>
> basename
> "Returns the base of the basename,
> i.e.
> /foo/gloops.taz basename is 'gloops.taz'
> / basename is '/'"
>
> Pragmas do not work well i.e.,
> basename
> "Returns the base of the basename"
>   'gloops.taz'>
>
>
> We should invent a syntax to be put inside comments and that we can easily
> parse because we need to improve
> the use and discovery of the library.
>
> I was thinking about
>
> basename
> "Returns the base of the basename"
> "
> '/foo/gloops.taz' asFileReference basename
> >>> 'gloops.taz'
> "
>
> Do you have any idea?
>
> I cannot not do anything and just complain that our methods are not that
> well documented.
> We as a community should take this and build an super cool system.
>
> I tried and defined >>> on Object to see if it works!
>
> Object >>> aResultingObject
> "If the method comment contains >>> then it is a pharo documentated
> test. We can check that it is true."
>
> "
> '/foo/gloops.taz' asFileReference basename
>>>> 'gloops.taz'
> "
>
> ^ self = aResultingObject
>
>
> Stef
>
>
>

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Nicolai Hess]

2016-09-15 20:45 GMT+02:00 stepharo :

> Hi all
>
> I want something similar in the spirit to PythonDocTest
> https://docs.python.org/2/library/doctest.html
>
> I'm talking about
>
> basename
> "Returns the base of the basename,
> i.e.
> /foo/gloops.taz basename is 'gloops.taz'
> / basename is '/'"
>
> Pragmas do not work well i.e.,
> basename
> "Returns the base of the basename"
>   'gloops.taz'>
>
>
> We should invent a syntax to be put inside comments and that we can easily
> parse because we need to improve
> the use and discovery of the library.
>
> I was thinking about
>
> basename
> "Returns the base of the basename"
> "
> '/foo/gloops.taz' asFileReference basename
> >>> 'gloops.taz'
> "
>
> Do you have any idea?
>
> I cannot not do anything and just complain that our methods are not that
> well documented.
> We as a community should take this and build an super cool system.
>
> I tried and defined >>> on Object to see if it works!
>
> Object >>> aResultingObject
> "If the method comment contains >>> then it is a pharo documentated
> test. We can check that it is true."
>
> "
> '/foo/gloops.taz' asFileReference basename
>>>> 'gloops.taz'
> "
>
> ^ self = aResultingObject
>
>
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
>
>
>
'From Pharo6.0 of 13 May 2016 [Latest update: #60225] on 15 September 2016 at 
10:27:15.932951 pm'!
IconStyler subclass: #ExampleIconStyler
instanceVariableNames: ''
classVariableNames: ''
poolDictionaries: ''
category: 'Reflectivity-Tools-Breakpoints'!

!AbstractFileReference methodsFor: 'accessing' stamp: 'NicolaiHess 9/15/2016 
22:25'!
basename
"Returns the basename, i.e. /foo/gloops.taz basename is 'gloops.taz'
` '/foo/gloops.taz' asFileReference basename -> 'gloops.taz'.` <- 
suceeds, no output
` '/foo/gloops.taz' asFileReference basename -> 'gloops.ta'.`   <- 
fails, shows asserter
` '/foo/gloops.taz' asFileReference basename` < opens inspector

"
^ self fullPath basename! !


!ExampleIconStyler methodsFor: 'as yet unclassified' stamp: 'NicolaiHess 
9/15/2016 14:37'!
iconBlock: aNode
^ (self exampleIsFaulty: aNode)
ifTrue: [ self notifySourceError: aNode ]
ifFalse: [self runExampleBlock: aNode]! !

!ExampleIconStyler methodsFor: 'as yet unclassified' stamp: 'NicolaiHess 
9/15/2016 14:38'!
iconFor: aNode
^ (self exampleIsFaulty: aNode)
ifTrue: [ self iconProvider iconNamed: #smallWarning ]
ifFalse: [ self iconProvider iconNamed: #smallInfo ]! !

!ExampleIconStyler methodsFor: 'as yet unclassified' stamp: 'NicolaiHess 
9/15/2016 14:35'!
exampleIsFaulty: aNode
^ aNode comments
anySatisfy: [ :commentNode | commentNode exampleNodes 
anySatisfy:[:node |
node value isFaulty ]]! !

!ExampleIconStyler methodsFor: 'as yet unclassified' stamp: 'NicolaiHess 
9/15/2016 14:39'!
notifySourceError: aNode
^ [ | examples faultyExample |
examples := aNode comments flatCollect: #exampleNodes.
faultyExample := examples detect: [ :example | example value isFaulty ].
RBParser parseExpression: faultyExample value source ]! !

!ExampleIconStyler methodsFor: 'as yet unclassified' stamp: 'NicolaiHess 
9/15/2016 12:53'!
shouldStyleNode: aNode
^ (aNode isMethod and: [ aNode comments isEmpty not ])
and: [ aNode comments anySatisfy: [ :commentNode | commentNode 
exampleNodes isNotEmpty ] ]! !

!ExampleIconStyler methodsFor: 'as yet unclassified' stamp: 'NicolaiHess 
9/15/2016 14:44'!
iconLabel: aNode
"3+4"
^ (self exampleIsFaulty: aNode)
ifTrue: [ 'Faulty Example' ]
ifFalse: [ 'Runnable Examle' ]! !

!ExampleIconStyler methodsFor: 'as yet unclassified' stamp: 'NicolaiHess 
9/15/2016 

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Esteban A. Maringolo]

2016-09-15 17:09 GMT-03:00 Tudor Girba :
> However, one thing to keep in mind is that one reason why these solutions 
> exist is because they assume no UI environment. Thus, the only thing they 
> have is text and the solution is built around it.
>
> In Pharo, we can think of concatenating information in the environment. If we 
> have a casual connection between examples and the code they exemplify, the 
> interface can provide all this information at the same time. The advantage 
> here is that the syntax remains simple.

+1

I wouldn't like that syntax, nor PharoDoc (a la JavaDoc), nor anything
"polluting" the code that way.

The comment or examples can be attributes of the method itself, just
like the class comment are today.

Regards!

Esteban A. Maringolo

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[Tudor Girba]

Hi,

I think this is an interesting idea.

However, one thing to keep in mind is that one reason why these solutions exist 
is because they assume no UI environment. Thus, the only thing they have is 
text and the solution is built around it.

In Pharo, we can think of concatenating information in the environment. If we 
have a casual connection between examples and the code they exemplify, the 
interface can provide all this information at the same time. The advantage here 
is that the syntax remains simple.

At the same time, we also want to have Pillar more thoroughly supported in our 
tools. Could it be that we could extend Pillar to support literate programming?

Cheers,
Doru


> On Sep 15, 2016, at 8:45 PM, stepharo  wrote:
> 
> Hi all
> 
> I want something similar in the spirit to PythonDocTest 
> https://docs.python.org/2/library/doctest.html
> 
> I'm talking about
> 
> basename
>"Returns the base of the basename,
>i.e.
>/foo/gloops.taz basename is 'gloops.taz'
>/ basename is '/'"
> 
> Pragmas do not work well i.e.,
> basename
>"Returns the base of the basename"
>  'gloops.taz'>
> 
> 
> We should invent a syntax to be put inside comments and that we can easily 
> parse because we need to improve
> the use and discovery of the library.
> 
> I was thinking about
> 
> basename
>"Returns the base of the basename"
>"
>'/foo/gloops.taz' asFileReference basename
>>>> 'gloops.taz'
>"
> 
> Do you have any idea?
> 
> I cannot not do anything and just complain that our methods are not that well 
> documented.
> We as a community should take this and build an super cool system.
> 
> I tried and defined >>> on Object to see if it works!
> 
> Object >>> aResultingObject
>"If the method comment contains >>> then it is a pharo documentated test. 
> We can check that it is true."
> 
>"
>'/foo/gloops.taz' asFileReference basename
>   >>> 'gloops.taz'
>"
> 
>^ self = aResultingObject
> 
> 
> Stef
> 
> 

--
www.tudorgirba.com
www.feenk.com

"It's not how it is, it is how we see it."

[Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

[stepharo]

Hi all

I want something similar in the spirit to PythonDocTest 
https://docs.python.org/2/library/doctest.html


I'm talking about

basename
"Returns the base of the basename,
i.e.
/foo/gloops.taz basename is 'gloops.taz'
/ basename is '/'"

Pragmas do not work well i.e.,
basename
"Returns the base of the basename"
 'gloops.taz'>



We should invent a syntax to be put inside comments and that we can 
easily parse because we need to improve

the use and discovery of the library.

I was thinking about

basename
"Returns the base of the basename"
"
'/foo/gloops.taz' asFileReference basename
>>> 'gloops.taz'
"

Do you have any idea?

I cannot not do anything and just complain that our methods are not that 
well documented.

We as a community should take this and build an super cool system.

I tried and defined >>> on Object to see if it works!

Object >>> aResultingObject
"If the method comment contains >>> then it is a pharo documentated 
test. We can check that it is true."


"
'/foo/gloops.taz' asFileReference basename
   >>> 'gloops.taz'
"

^ self = aResultingObject


Stef