On Thu, Aug 18, 2016 at 9:34 AM, stepharo <stepharo@free.fr> wrote:
Hi guys
I'm fed up to get methods without comments and without little examples. In
+1 ! We can setup a small group of people interested to build examples at ESUG.
FileSystem, I wrote most of the comments and I tried to add an obvious example:
basenameWithIndicator "Returns the basename with the indicator appended, i.e. /foo/gloops.taz basenameWithIndicator is 'gloops.taz', whereras /foo basenameWithIndicator is 'foo/'"
^ self basename , self indicator
Now let us look at:
withExtension: aString ^ self withPath: (self path withExtension: aString)
Nice comment :(
I would like to support PythonDoctest (yes we are not the only one to have ideas let us face is dear friends)
+1 https://en.wikipedia.org/wiki/Doctest
def multiply(a, b): """ >>> multiply(4, 3) 12 >>> multiply('a', 3) 'aaa' """ return a * b
Because we can make sure that the comments are accurate.
withExtension: aString
"Returns a new file reference with a different file extension"
<exp: '/tmp/file.txt' asFileReference withExtension: 'log'
value: '/tmp/file.log' asFileReference >
^ self withPath: (self path withExtension: aString)
It will help us to have a distinction between printOn: and displayString
Typically
'/tmp/file.txt' asFileReference withExtension: 'log'
printString is bad
since it returns File @ '/tmp/file.log' which is not an reexecutable expression
So let me know what you think. - tell me that we have already test unit (yes the ones I wrote too) => they do not have the same purpose
For me this is getting to be important.
Maybe a subset of Pharo could be defined as core with a kind of API freeze, so we can spend some time documenting the corresponding methods and classes. -- Serge Stinckwich UCBN & UMI UMMISCO 209 (IRD/UPMC) Every DSL ends up being Smalltalk http://www.doesnotunderstand.org/