- Pharo-dev - lists.pharo.org

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

by stepharo

Le 16/9/16 Ã 15:26, Damien Pollet a Ã©crit : > On 16 September 2016 at 13:42, ClÃ©ment Bera <bera.clement(a)gmail.com > <mailto:bera.clement@gmail.com>> wrote: > > Why don't you just change nautilus to have two text areas, one > with the test corresponding to the method and the other one with > the method's code ? > > > Exactly, we already have that with class comments, so why not methods > (and while we're at it, package comments too) I love you guys. Let us change MCZ binary storage, pharo language metamodel and more while we are at it. Not talking about merging and others. Sorry there is a huge tradeoffs with simplicity and gain. And you are just jumping into building a monster for ONE LINERS.... Repeat after me ONE LINERS. I prefer to keep my energy for worth large enhancements and grab low hanging fruits when I see them. And Nicolai showed it to us. We cn get some variation and get all the easy benefits. Daemons of over-engineering are tempting us because this is cooler to to design something complex. But KISS to the rescue. Stef > > A separate method comment would make it clear that it's intended as > API documentation for users of the method (and then the comment inside > the method's source can be really a development comment). Another > advantage is that its syntax won't have to deal with being between > quotes and all the indentation/escapement hassles that come with > inserting a syntax inside another oneâ¦ > > -- > Damien Pollet > type less, do more [ | ] http://people.untyped.org/damien.pollet

Sept. 16, 2016

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

by stepharo

> This is what I thought first, we already have the association between > methods and tests, Nautilus can detect if there > is a corresponding test , for example browse Fraction>>truncated, it > will show a test icon, that will run the test > FractionTest>>#testTruncated. > This works already good, and I think we don't need special comments or > pragmas for this. > > But what stef wants is > 1. Method docs with examples, so a user can see an example usage of a > method (sunit test methods sometimes aren't good "examples") > 2. We already had (and still have) some method docs where the example > code just won't work anymore because the methods or classes used > by the example were removed, renamed. So, it would be good if we can > extract these examples and run them automatically to make sure they > are still working. > > But yes, maybe we can still solve this with better Tools, not working > only on the plain text in comments. This can be done in addition but first we should be able to encode them.

Sept. 16, 2016

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

by stepharo

+ 1 Changing the language metamodel for simple validated comments is a huge effort for nothing. Clement is good at VM level but not at other level :) Stef Le 16/9/16 Ã 14:18, Denis Kudriashov a Ã©crit : > > 2016-09-16 13:42 GMT+02:00 ClÃ©ment Bera <bera.clement(a)gmail.com > <mailto:bera.clement@gmail.com>>: > > Why don't you just change nautilus to have two text areas, one > with the test corresponding to the method and the other one with > the method's code ? > > You're saying: > /Their values is active documentation that can be automatically > validated./ > That can also be applied to test we've already had with SUnit. If > the only difference you want is to display the test next to the > method, then it's an IDE problem, nothing has to be changed but > the IDE. > > In python they have no other choices than putting tests in > comments because their IDE is a text editor, they cannot create > other panes or anything like that. > > > It is of course true. But Stef suggestion is really much much simpler. > It is just convention how to write examples inside comments. Then > tools could work with them and Nicolai already provide simple > extension for Nautilus. > We already has a lot of comments with examples inside. Making them > discoverable and testable will be nice. >

Sept. 16, 2016

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

by stepharo

Le 16/9/16 Ã 13:42, ClÃ©ment Bera a Ã©crit : > Why don't you just change nautilus to have two text areas, one with > the test corresponding to the method and the other one with the > method's code ? > > You're saying: > /Their values is active documentation that can be automatically > validated./ > That can also be applied to test we've already had with SUnit. If the > only difference you want is to display the test next to the method, > then it's an IDE problem, nothing has to be changed but the IDE. and you want to create different semantic objects... well you underestimate the amount of work. Ask pavel just to get a semantically model for Pharo just plain pharo with Slot and Traits. Stef > > In python they have no other choices than putting tests in comments > because their IDE is a text editor, they cannot create other panes or > anything like that. Clement how do you save/store/merge.... in a method it is cheap and working. > > On Fri, Sep 16, 2016 at 1:21 PM, stepharo <stepharo(a)free.fr > <mailto:stepharo@free.fr>> wrote: > > >> Hi, >> >> I was thinking on the metro way to work, and I also saw that this >> discussion is actually split in multiple threads, so it was not >> easy to follow :). >> >> Some of my feelings about this: >> >> - Pragmas are nice because they are easy to "interpret". Parsing >> them is already provided. However, putting expressions or long >> examples into them starts to be awkward. It seems it's pushin the >> syntax too much, isn't it? >> >> - Comments are nice because they are ignored! But right now >> comments are simple plain text. This thread is to convert *some* >> comments into executable examples. But this should be just some >> comments and not all of them, am I right? So what happens when we >> want to have comments written in Pillar for example? What I mean >> is that having examples is just an example of something we would >> like to do with comments. >> >> But we can also imagine having comment interpreters. Something >> like this: >> >> ">>>PillarDoc >> !This is a Pillar title >> And I'm just a paragraph >> And I can link a class like @Object. >> " >> >> >> ">>>ExampleDoc >> self assert: '/foo/gloops.taz' asFileReference basename equals: >> 'gloops.taz' >> " >> > > We could have for class comment > > ">>>UMLDescription > UMLClass named: 'Visitor' > > Arrow from: > > But this can start to be complex > " > >> What I like from this is that: >> - comments that do not specify an interpreter are just plain >> old text. Thus backward compatible. >> - comments that specify an interpreter that is not present, are >> just plain old text. A decoupling as it happens with the settings. >> - an ExampleDoc interpreter can be just a test case instance, >> thus we could use assertions instead of special >>> messages. > I do not know because all the comments should be pillar compatible. > If you do not use pillar commands you just get plain text. > You see we can easily detect comment too: if a text contains >>> > then it is a doc > > Then > ExampleDoc > is an extra syntax. > > I'm not found with the > self assert: > because it feels like something coming out of nowhere. We will > have to explain: yes self is bound to an instance of the testCase... > and to me this is implementation details: > if I give expr1 and expr2 the implementation can build self > assert: expr1 equals: expr2 > > I liked the simplicity of nicolai' solution > I would just have a comment and a message >>> so that we > => nearly no syntax change > => something really lightweight and optional > > > What I care is that > > - we get simple examples right in the method > - one line no more. > - that these examples are correct and always validated (I do > not see them as tests), their values is more in the correct > documentation > than the tests. They are basic output. I do not want to have > full code in the method, in that case this should go one class > side example > or plain tests. > >> >> Things that would require more thought: >> - there is an overlap between these interpreted comments and >> pragmas... There are for sure cases that solutions can be >> imagined with both. > I do not think that expressions can fit inside pragmas >> - there is an overlap between examples and test cases. I saw >> many people that argued that already. I am not against examples, >> but I think we should (whichever implementation is chosen) draw a >> line and set some guidelines. > To me I do not care that they are tests. > Their values is active documentation that can be automatically > validated. I do not expect to run them but the system > can garantee that they are correct. > >> Stef, probably you have already in mind when you want a test case >> and when an example and what's the distance. It would be good if >> we can transform that implicit thought in something explicit >> (maybe even a lint rule in the future?) > I do not get what you mean here. > > For me a test is a scenario. > If I do that and that then this happens > a test can use a class example > > Now for me a test should not rely one a online part of method > comment. > > These onliners are just make the method comments better. > > > > >> >> Guille >> >> -------- Original Message -------- >>> >>> Hi nicolai >>> >>> >>> I was thinking that I would prefer to have >>> >>> >>> "` '/foo/gloops.taz' asFileReference basename -> 'gloops.taz'.`" >>> >>> >>> instead of >>> ` '/foo/gloops.taz' asFileReference basename -> >>> 'gloops.taz'.` <- suceeds, no output >>> >>> So that we can use ` in the future in plain code. >>> Also it has the advantage that it is backward compatible. >>> >>> Else we could have >>> >>> `` >>> But I do not know. >>> >>> Tell me what you think. >>> >>> I would love to browse the complete system to convert existing >>> one liner with such >>> >>> Stef >>> >>>> >>>> Ok, this is a quick hack ( do not look at the code :), yes >>>> using regex here is a bit fragil) >>>> >>>> You can add code in comments between backticks (`) >>>> The formatter will highlight the text like smalltalk code (or >>>> not if it is not valid code). >>>> + an icon styler with an icon showing a warning icon for faulty >>>> code or an information icon otherwise >>>> you can click on the icon, >>>> >>>> if the code is an association >>>> >>>> expression -> result >>>> >>>> it executes the expression and compares it with the result, >>>> (with assert:equals: ) opens debugger if it fails and does >>>> nothing otherwise >>>> >>>> if the code is just an expression, it opens an inspector. >>>> >>>> This is just one way to do some tests and experiments with this >>>> idea, don 't yet know if this is a good idea or if >>>> we can / should find a better way to connect code with examples. >>>> >>>> first result, I find expressions in comments, highlighted as >>>> code, confusing :) >>>> >>>> (file in attached cs in a recent pharo 6.0 and look at the >>>> method AbstractFileReference>>#baseName . Or >>>> add an expression with backticks in a method comment >>>> ` your code here ` >>>> >>>> >>>> >>>> Stef >>>> >>>> >>>> >>> >> > >

Sept. 16, 2016

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

by stepharo

> Hi > > 2016-09-16 13:21 GMT+02:00 stepharo <stepharo(a)free.fr > <mailto:stepharo@free.fr>>: > >> - there is an overlap between examples and test cases. I saw >> many people that argued that already. I am not against examples, >> but I think we should (whichever implementation is chosen) draw a >> line and set some guidelines. > To me I do not care that they are tests. > Their values is active documentation that can be automatically > validated. I do not expect to run them but the system > can garantee that they are correct. > > > How it could work? Somebody need to press button to check all comments > are valid. No? the integration run the validation and says that system documentation is ok. We do that all the time with Quqlity rules.

Sept. 16, 2016

Re: [Pharo-dev] Author / TestRunner interaction in fresh image

by stepharo

> Yes, that would be great. > > I just wander if the increased complexity pays off... normally if I am > running my tests I do not have lots of tasks in mind, I will decide > what to do next after seeing that my tests are green. Maybe I just > want to browse some code, I do not need super fancy features. Nico the problems are not your tests but the tests somebody else wrote and that may destroy the package integrity or think like that. Stef

Sept. 16, 2016

Re: [Pharo-dev] Maintainer of DependencyAnalyser: Action needed

by stepharo

This is christophe! > Whoever maintains DependencyAnalyser: There is a fix ready since 22 August 2016. > > We need to get this into the system *soon*. > > https://pharo.fogbugz.com/f/cases/18963/DANode-browseClass-sends-unimplemen… > > > Marcus >

Sept. 16, 2016

Re: [Pharo-dev] [pharo-project/pharo-core] edd9f3: 60220

by Eliot Miranda

Hi All, _,,,^..^,,,_ (phone) > On Sep 14, 2016, at 10:50 PM, Marcus Denker <marcus.denker(a)inria.fr> wrote: > > >>> >>> We can change it back and maybe add support for the reformatter to not convert it to the literal array #(3 #+ 4) . >> >> I do not know in fact this is why I asked :) >> Now may be my idea to use pragma to get something like pythondoctest is a bad idea >> but I really want to have literal programming. >> What do you think? > I like the idea to show examples/tests close to code, but pragmas are not really good... > >> If we have ' ' then it would be good that the syntax higlighter works with a special mode inside the ' ' > > it is just a string. How do you know that it contains code? > > Would you highlight all string in all code as if it contained code? Or would you add this just for > Pragmas? But even there, strings are string, not code. > > I think we can conclude that pragmas are not a good solution to the problem, as they are far > too limited to express code. I think that's not a safe conclusion. We know from Igor's use of Kieran arrays for C signatures in the UFFI, and can easily extrapolate here, that arbitrary Smalltalk expressions /can/ be expressed in literal arrays. S expressions work for lisp. In this particular case special casing pretty printing of literal arrays in pragmas would be all that's needed to make the code look beautiful. Why throw the baby out with the bath water? It would be so easy to make this work well. The only thing I'd do would be to print like this to make it clear that the argument t is a literal Array and not some magic form of code: <expr: #(3 + 4) result: 7> > > Marcus > > > > > >

Sept. 16, 2016

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

by philippe.back＠highoctane.be

How is all of this PackageManifest mechanism working? Doc anywhere? Phil Le 16 sept. 2016 17:02, "Nicolai Hess" <nicolaihess(a)gmail.com> a Ã©crit : 2016-09-16 0:19 GMT+02:00 phil(a)highoctane.be <phil(a)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 <stepharo(a)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 >> >> >> >

Sept. 16, 2016

Re: [Pharo-dev] Call for design for a literal programming doc similar to PythonDocTest

by Nicolai Hess

2016-09-16 0:19 GMT+02:00 phil(a)highoctane.be <phil(a)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 <stepharo(a)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 >> >> >> >

Sept. 16, 2016