Hi doru
Hi,
I like this problem very much. I think we are not leveraging the objects we
have in the image. Tests can help, but they are way too disconnected from the
code and they are not really useful for detailed questions.
I am also happy that you are considering the use of pragmas for this purpose.
As you know, Stefan Reichhart and I worked on the examples engine since a
couple of years and I think we now start to have a working solution.
I do not want 5 pragmas and dependencies between methods and examples.
KISS.
Pharo tends to forget KISS far too often recently.
You know exactly what I do not want: conceptual (and code) bloat.
Because this would be a significant departure from tests, we first wanted to
get a more thorough documentation of the current state before opening the
discussion to the community to see how this can fit in Pharo or at least in the
ecosystem. I think we will have this ready in a draft form in a couple of days,
and it would be great to have a critical discussion about it at ESUG.
My plate is really full. I have a super long list of things that I want
to discuss at ESUG.
Stef
Cheers,
Doru
On Aug 18, 2016, at 1:32 PM, stepharo <steph...@free.fr> wrote:
Tx serge
- I think that we should agree on the pragma or way to express it. May be we
can do the same as in Python and use a comment instead of a pragma. I prefer a
pragma because we can query them easily.
So any idea instead of
<exp: value:>
<expression: return: >
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)
- then incrementally we can start taking on system for example FS and use it.
Stef
Le 18/8/16 à 11:51, Serge Stinckwich a écrit :
On Thu, Aug 18, 2016 at 9:34 AM, stepharo <steph...@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.
--
www.tudorgirba.com
www.feenk.com
"Every thing has its own flow."
