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 <steph...@free.fr 
<mailto:steph...@free.fr>>:

    Hi all

    I want something similar in the spirit to PythonDocTest
    https://docs.python.org/2/library/doctest.html
    <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


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