Call for design for a literal programming doc similar to PythonDocTest

How is all of this PackageManifest mechanism working?

Doc anywhere?

Phil

Hi

2016-09-16 13:21 GMT+02:00 stepharo <[hidden email]>:

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

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 <[hidden email]> 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
    ` '/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

+ 1

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

2016-09-16 13:42 GMT+02:00 Clément Bera <[hidden email]>:

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. 

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.

On 16 September 2016 at 13:42, Clément Bera <[hidden email]> 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

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 <[hidden email]> 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"
     <expr: '''/foo/gloops.taz'' asFileReference basename' result: '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

On 16 September 2016 at 20:42, stepharo <[hidden email]> 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

+1

> On Sep 16, 2016, at 8:37 PM, stepharo <[hidden email]> 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.7000000000000001 g: 0.07 b: 0.07 alpha: 1.0). (Color r: 0.7000000000000001 .....}

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 unit tests are written like that. Some tests are mostly about testing corner cases or an implementation detail,

or other code that isn't even considered to be used outside of the test.

So, yes, we should do some more experiments and see.

 

Cheers,
Doru


> Stef
>
> Le 16/9/16 à 14:18, Denis Kudriashov a écrit :
>>
>> 2016-09-16 13:42 GMT+02:00 Clément Bera <[hidden email]>:
>> 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."