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