I can't remember ever using API docs in any language, dynamic or not. They give you the method signatures, but if you have, say, methodX(int, int, String), how are you supposed to guess what ints and what String the method actually needs, unless the methods are nothing but getters and setters (which I've never understood the point of) ? (I know, most give (int somename, int someothername, String whatever), but how often do are method names well thought through enough to imply definitively what the method needs?. It's my biggest issue with Algol-style syntax - the method caller is supposed to know how it works, rather than whoever actually wrote it. It's probably at least one of the reasons for the amount of OSS in Java, and more recently in JavaScript (though the latter is more no- style than Algol-style). I nearly always download the source to OSS libs although I rarely ever bother building it, so I know what a method does with the params, and I can be sure what params to give it. One of my favourite language fails can be reproduced by doing this: Declare a field private final in Java, initializing it either in the declaration or the constructor, and provide only a getter. Use the getter from another class and change the value of the local variable. Then use the getter again, but assign the value to a new local variable, and check the value. Guess what? The value is whatever you changed it to in your other local variable, although the API docs claim javac won't compile it. I tested this with Java 8, I haven't bothered to see if it was always like that or if they took the rule out of javac because it interfered with some syntactic parmesan, such as lambdas. I should copy my test code into VisualAge for Java and see if in fact it compiles with JDK 1.4.2, or if javac was changed in between 4 and 8, since the addition of various flavours of syntactic parmesan mostly started with Java 5. Not that it's all that important in one sense. If 'private' and 'final' were supposed to be guides for other developers to be careful if they're thinking about changing it, fine, anyone who doesn't isn't all that good a developer. But given the number of 'not very good' developers I've had the misfortune to work with in Java, it's more problematic than it should be. It also makes the pattern of a private field with a public setter even more useless, since the setter isn't needed to change the value. I always get dinged by whatever lint companies use for not bothering with that pattern, though, and pointing out that declaring the fields public accomplishes exactly the same thing never helps my case, because whatever lint they use, it has to be right, there's no way a non-lint developer might be right. Andrew Glynn -----Original Message----- Date: Wed, 11 Oct 2017 10:01:20 -0500Subject: Re: [Pharo-users] Behold Pharo: The Modern SmalltalkTo: pharo-users@lists.pharo.orgReply-to: Any question about pharo is welcome <pharo-users@lists.pharo.org>From: Offray Vladimir Luna Cárdenas <offray.l...@mutabit.com> Yes. I know them. I mean API docs as static files. I don't really sold on them compared with a live system and I don't think static API docs are critical for Pharo success. Cheers, Offray
On 11/10/17 09:52, Dimitris Chloupis wrote: > Ah > and my static website was built with Pillar and Bootstrap, > using > bootstrap templates was easy because Pillar supports mustache > that > makes html manipulation much easier > > > > http://www.kilon-alios.com > > > > Pillar of course is not made for generating websites but it’s > an > awesome Pharo library that allows for great degree of freedom > so I > thought , why not ? > > > On Wed, 11 Oct 2017 at 17:48, Dimitris Chloupis > <kilon.al...@gmail.com> wrote: > > > > > Docs are > > available in static online html format , at least the > > book I > > was working on > > > > > > > > Pharo By Example > > > > > > > > You can find those links here > > > > > > > > https://github.com/SquareBracketAssociates/UpdatedPharoBy > > Example > > > > > > > > Our documentation system , Pillar , outputs pdf , html > > and > > markdown files. > > > > > > > > If the book in question is built like PBE with CI of > > Inria > > where most Pharo related official projects are built then > > it > > should have at least pdf and html with online access so > > you > > can easily link to. > > > > > > > > Don’t quote me on this but I think the html output of > > pillar > > generate links even for paragraphs you can do an even > > more > > process linking to the documentation. > > > > > > On Wed, 11 Oct 2017 at 17:40, Offray Vladimir > > Luna Cárdenas <offray.l...@mutabit.com> > > wrote: > > > > > > > > > > > > The more I use Pharo, the less I use web > > > documentation. For me seems pretty suboptimal > > > compared > > > to live environment with code browser and GT- > > > Spotter. > > > Regarding the comment on Medium, it also took > > > me > > > little to find #raisedTo:, so the millage can > > > vary. > > > What I was missing was proper books for > > > particular > > > domains, but Pharo books are covering that. I > > > don't > > > know if a Q&A site could improve search-ability > > > for newbies (certainly you can find little > > > stuff in > > > Stack Overflow). > > > My bet is about trying to create more "end user" > > > tools (Grafoscopio is kind of this), besides > > > tools for > > > developers. There is a broad community of > > > people who > > > can be active contributors and members of the > > > community, welcome Pharo and live coding a lot > > > and > > > don't complain that much about stuff that is > > > not > > > already pretty similar to what they already > > > know > > > (being that only English MOOC or online static > > > html > > > docs). > > > Cheers, > > > Offray > > > > > > > > > > > > > > > > > > On > > > 11/10/17 07:34, Dimitris Chloupis wrote: > > > > > > > > > > > > > for me it is a yes and no situation, > > > > yes its very coold to have your entire > > > > system in > > > > your fingertips but Pharo has serious > > > > issues with > > > > code organisation and I find the lack of > > > > namespaces > > > > quite inconvenient. You have to be careful > > > > how to > > > > name your classes which does not sound to > > > > me very > > > > OOP friendly. > > > > > > > > > > > > > > > > Also the IDE does not handle > > > > spaggetification > > > > very well, sure you can find implementors > > > > , > > > > senders etc but if the execution chain is > > > > complex > > > > , welcome to spaggeti hell. But that is a > > > > problem > > > > with most other IDEs if not all as well. > > > > Problem > > > > is in this case that we have the very > > > > good rule of > > > > using sort methods which multiplies this > > > > problem > > > > and makes navigation even harder. Code > > > > becomes > > > > much easier to read per method and > > > > messages but > > > > much harder to understand in a bird eye > > > > view. > > > > > > > > > > > > > > > > Some of that pain has been aleviated with > > > > the > > > > introduction of GTSpotter which I have > > > > praised > > > > quite a lot and I will continue to do so. > > > > But yeah > > > > there are more needed to be done in the > > > > department > > > > to make Pharo code navigation a more > > > > comfortable > > > > task. > > > > > > > > > > > > > > > > > > > > On Wed, Oct 11, 2017 at 2:57 PM Vitor > > > > Medina Cruz <vitormc...@gmail.com> > > > > wrote: > > > > > > > > > > > > > > > > > > > > > > > > > > > I dunno, maybe I’m weird, but I > > > > > find > > > > > the System Browser a fantastic way > > > > > to explore > > > > > the class library. If you find a > > > > > class or > > > > > method that isn’t well documented, > > > > > write a > > > > > comment and send a change request. > > > > > Stef told > > > > > me this ages ago. I might add, if > > > > > you find a > > > > > bug you should write a test that > > > > > exercises the > > > > > bug and submit it on fogbugz (the > > > > > bug tracking > > > > > system). > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > I will reference of response of > > > > > mine to a similar opinion made by > > > > > Richard: https://medium.com/@vitormcruz/i-disagree-it-is-much > > > > > -harder-to-find-anything-in-the-environment-c6bdd44f6eea > > > > > My 2 cents. > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > On Tue, Oct 10, 2017 at > > > > > 11:59 PM, john pfersich <jpfersich@ > > > > > gmail.com> > > > > > wrote: > > > > > > > > > > > > > > > > > On Oct 10, 2017, at 09:58, > > > > > > horrido > > > > > > <horrido.hobb...@gmail.com> > > > > > > wrote: > > > > > > > > > > > > > > > > > > > > > > > > > > Interestingly, I'm getting > > > > > > a fair > > > > > > amount of pushback on this. > > > > > > Personally, I > > > > > > > > > > > > > think it would be very > > > > > > helpful to > > > > > > have a live (updatable, so as > > > > > > to keep it > > > > > > > > > > > > > current) reference page for > > > > > > the class > > > > > > library, something that > > > > > > developers can > > > > > > > > > > > > > easily look up what they > > > > > > need. After > > > > > > all, most of the power of > > > > > > Pharo comes > > > > > > > > > > > > > from the class library and > > > > > > we need to > > > > > > make it as accessible as > > > > > > possible to > > > > > > > > > > > > > less experienced Pharoers > > > > > > (i.e., > > > > > > beginners). > > > > > > > > > > > > > > > > > > > > > > > > > > Exploring the class library > > > > > > through > > > > > > the System Browser is very > > > > > > inefficient. > > > > > > > > > > > > > This is further exacerbated > > > > > > by the > > > > > > fact that many classes and > > > > > > methods are > > > > > > > > > > > > > simply not well-documented > > > > > > (containing a cursory remark > > > > > > which is just > > > > > > barely > > > > > > > > > > > > > useful). > > > > > > > > > > > > > > > > > > > > > > > > > I dunno, maybe I’m weird, but I > > > > > > find > > > > > > the System Browser a fantastic > > > > > > way to > > > > > > explore the class library. If > > > > > > you find a > > > > > > class or method that isn’t well > > > > > > documented, > > > > > > write a comment and send a > > > > > > change request. > > > > > > Stef told me this ages ago. I > > > > > > might add, if > > > > > > you find a bug you should write > > > > > > a test that > > > > > > exercises the bug and submit it > > > > > > on fogbugz > > > > > > (the bug tracking system). > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > I realize that creating a > > > > > > live > > > > > > reference page is not easy > > > > > > to do. In > > > > > > fact, > > > > > > > > > > > > > it's a lot of work. But > > > > > > the absence > > > > > > of such a page is a real > > > > > > obstacle to > > > > > > > > > > > > > Pharo acceptance. > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > horrido wrote > > > > > > > > > > > > >> Thanks. I gave your > > > > > > answer > > > > > > verbatim. I also added the > > > > > > following > > > > > > paragraph: > > > > > > > > > > > > >> > > > > > > > > > > > > >> The problem I find with > > > > > > today’s > > > > > > developers is that they are > > > > > > rather > > > > > > > > > > > > >> closed-minded. They are > > > > > > rigid > > > > > > and inflexible, and not > > > > > > willing to adapt > > > > > > to > > > > > > > > > > > > >> new and different ways > > > > > > of doing > > > > > > things. In my generation > > > > > > (circa > > > > > > > > > > > > >> 1980–1990), > > > > > > > > > > > > >> people didn’t have a > > > > > > problem > > > > > > with trying different > > > > > > technologies. > > > > > > That’s > > > > > > > > > > > > >> why > > > > > > > > > > > > >> I had no issue with > > > > > > learning > > > > > > Smalltalk 10 years ago, > > > > > > after I had > > > > > > retired > > > > > > > > > > > > >> from a 20-year-long > > > > > > career in C > > > > > > systems programming and > > > > > > FORTRAN > > > > > > scientific > > > > > > > > > > > > >> programming. > > > > > > > > > > > > >> > > > > > > > > > > > > >> > > > > > > > > > > > > >> > > > > > > > > > > > > >> Sven Van Caekenberghe-2 > > > > > > wrote > > > > > > > > > > > > >>>> On 6 Oct 2017, at > > > > > > 14:54, horrido < > > > > > > > > > > > > >> > > > > > > > > > > > > >>> horrido.hobbies@ > > > > > > > > > > > > >> > > > > > > > > > > > > >>> > wrote: > > > > > > > > > > > > >>>> > > > > > > > > > > > > >>>> I received this > > > > > > comment > > > > > > from someone who > > > > > > complained: > > > > > > > > > > > > >>>> > > > > > > > > > > > > >>>> *What about the lack > > > > > > of > > > > > > documentation? From time to > > > > > > time I’ve > > > > > > checked > > > > > > > > > > > > >>>> some > > > > > > > > > > > > >>>> SmallTalk > > > > > > implementations like > > > > > > Squeak, > > > > > > GNU-Smalltalk and now > > > > > > Pharo. Of > > > > > > > > > > > > >>>> these, only > > > > > > GNU-SmallTalk appears to > > > > > > have a free, > > > > > > official programming > > > > > > > > > > > > >>>> guide > > > > > > > > > > > > >>>> and core library > > > > > > reference that any serious > > > > > > programmer > > > > > > expects from a > > > > > > > > > > > > >>>> language. > > > > > > > > > > > > >>>> > > > > > > > > > > > > >>>> https://www.gnu.org/so > > > > > > ftware/smalltalk/manual-base/html_node/* > > > > > > > > > > > > >>>> > > > > > > > > > > > > >>>> I pointed to Pharo's > > > > > > documentation but then he > > > > > > came back > > > > > > with: > > > > > > > > > > > > >>>> > > > > > > > > > > > > >>>> *Then show me a link > > > > > > of > > > > > > the free, maintained > > > > > > reference > > > > > > documentation for > > > > > > > > > > > > >>>> the > > > > > > > > > > > > >>>> classes that form “the > > > > > > core library”, like this > > > > > > one for Python > > > > > > > > > > > > >>>> (https://docs.python.o > > > > > > rg/3/library/index.html)* > > > > > > > > > > > > >>>> > > > > > > > > > > > > >>>> It's true, most > > > > > > Smalltalks do not have a > > > > > > core library > > > > > > reference, not > > > > > > > > > > > > >>>> even > > > > > > > > > > > > >>>> VisualWorks! So what > > > > > > is > > > > > > the proper response to this > > > > > > complaint? > > > > > > > > > > > > >>> > > > > > > > > > > > > >>> The first answer is > > > > > > that > > > > > > Pharo/Smalltalk is unique > > > > > > in that a > > > > > > running > > > > > > > > > > > > >>> system/IDE contains > > > > > > _all_ > > > > > > source code, _all_ > > > > > > documentation (class, > > > > > > > > > > > > >>> method, > > > > > > > > > > > > >>> help, tutorial), _all_ > > > > > > unit > > > > > > tests and _all_ runnable > > > > > > examples in a > > > > > > very > > > > > > > > > > > > >>> easy, accessible way. > > > > > > It > > > > > > takes some getting used to, > > > > > > but this is > > > > > > actually > > > > > > > > > > > > >>> better and much more > > > > > > powerful than any > > > > > > alternative. > > > > > > > > > > > > >>> > > > > > > > > > > > > >>> The second answer is > > > > > > that > > > > > > there are lots of books and > > > > > > articles > > > > > > that take > > > > > > > > > > > > >>> the classic/structured > > > > > > book/paper approach. There > > > > > > is > > > > > > > > > > > > >>> http://books.pharo.org, > > > > > > http://themoosebook.org, > > > > > > > > > > > > >>> http://book.seaside.st/ > > > > > > book, > > > > > > http://medium.com/concernin > > > > > > g-pharo > > > > > > and many > > > > > > > > > > > > >>> more. > > > > > > > > > > > > >>> > > > > > > > > > > > > >>>> Thanks. > > > > > > > > > > > > >>>> > > > > > > > > > > > > >>>> > > > > > > > > > > > > >>>> > > > > > > > > > > > > >>>> -- > > > > > > > > > > > > >>>> Sent from: http://foru > > > > > > m.world.st/Pharo-Smalltalk-Users-f1310670.html > > > > > > > > > > > > >>>> > > > > > > > > > > > > >> > > > > > > > > > > > > >> > > > > > > > > > > > > >> > > > > > > > > > > > > >> > > > > > > > > > > > > >> > > > > > > > > > > > > >> -- > > > > > > > > > > > > >> Sent from: http://forum. > > > > > > world.st/Pharo-Smalltalk-Users-f1310670.html > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > -- > > > > > > > > > > > > > Sent from: http://forum.w > > > > > > orld.st/Pharo-Smalltalk-Users-f1310670.html > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
