Call for design for a literal programming doc similar to PythonDocTest

---------- Forwarded message ----------
From: Nicolai Hess <[hidden email]>
Date: 2016-09-16 17:01 GMT+02:00
Subject: Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest
To: Pharo Development List <[hidden email]>

2016-09-16 0:19 GMT+02:00 [hidden email] <[hidden email]>:

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)

Anyone looked at this ?

Is this what we can use for supporting and editing package comments? I am not sure if the

use of package manifests is how we wanted to implement package comments. Any other ideas?

I can open a fogbugzs issue and refine this implementation a little bit.

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

2016-10-10 21:29 GMT+02:00 [hidden email] <[hidden email]>:

Whatever would be better than what we have now.

I like what you propose, makes sense and doesn't loads the UI with more stuff.

I am willing to test your implementation for sure.

it is in now (Pharo 60267). If anything is missing, not working or whatever, please report back.

(Packages without package manifest class show just nothing, but you can add a new package comment (package manifest class will be created).

If a package manifest class exists, but without a #description you text appears in the comment pane ("No package comment in this manifest .... please add a comment").

 

Phil

On Mon, Oct 10, 2016 at 6:56 PM, Nicolai Hess <[hidden email]> wrote:

---------- Forwarded message ----------
From: Nicolai Hess <[hidden email]>
Date: 2016-09-16 17:01 GMT+02:00
Subject: Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest
To: Pharo Development List <[hidden email]>

2016-09-16 0:19 GMT+02:00 [hidden email] <[hidden email]>:

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)

Anyone looked at this ?

Is this what we can use for supporting and editing package comments? I am not sure if the

use of package manifests is how we wanted to implement package comments. Any other ideas?

I can open a fogbugzs issue and refine this implementation a little bit.

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