On Aug 14, 2009, at 7:00 AM, Brian Brown wrote:
On Aug 13, 2009, at 2:49 PM, Stéphane Ducasse wrote:
But you know you can also propose a solution with code. :) Take DrDoc and improve it. I agree more than 200% with you but my day job in not improving pharo or squeak. Pharo is a nice project but I have plenty of other things that I have to do (admin, research, PhD students....)
I know that, you do amazing amounts in spite of your responsibilities and I really appreciate it. The only reason I sent you an email is because you were/are working on the PackageInfo replacement, so it seemed appropriate.
Oh Yes!
Is DrDoc on SqueakSource? I'll take a look.
Yes I would be more than happy if someone could take the lead there. I could embed images (UML diagram). I designed in a way that it does not depend on an existing superclass so that we can load the package and its metadata in any squeak/pharo version (so the design is suboptimal from a OO perspective). Stef
- Brian
Stef
So far we should invent it. And I totally agree with you. If people do not see the good doc they will not write good comment. I started to work on DrDoc a kind of package meta data to add documentation to a package but it got stole I should push that again. What would be nice is to take one package and do it well as an example.
It think it should be possible to write documentation at the package level. So developpers have a place where they can write an overview of their package. When we click on a package, documentation should be displayed by default or easily.
Yes! Here is a post I made in April of 2003:
The biggest frustration with using comments is that there is no good "starting place" for a given class category. For example, go browse the Seaside classes and categories and figure out where one should start. You can repeat this exercise for any number of categories. I propose that we we add a documentation attribute to the PackageInfo stuff, so there is a category level documentation spot, with links to the appropriate class comments.
Any thoughts? I didn't get any response, and I sent a similar type of thought to Stef recently, but he's so busy I don't even know if he read my email :)
- Brian
In the rubygems world, it is a common practice to write documentation in a README file which is displayed by RDoc on startup page (github works the same way). It seems to me that there's the same level of comment between Ruby class/methods and Pharo. The documentation at the package level may be the difference.
Python has a real documentation effort.Each release come with its up to date documentation. It's a release criteria. Python shares some similarities with Pharo as they both have "batteries included". May be there should have a process to contribute to a centralized Pharo documentation which can be accessed within the IDE.
Laurent. _______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
_______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
_______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
_______________________________________________ Pharo-project mailing list Pharo-project@lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project