2016-09-16 0:19 GMT+02:00 p...@highoctane.be <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 <steph...@free.fr> 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
>>
>>
>>
>

Attachment: package_comment.cs
Description: Binary data

Reply via email to