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 >>>> [email protected] >>>> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project >>> >>> _______________________________________________ >>> Pharo-project mailing list >>> [email protected] >>> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project >> >> >> _______________________________________________ >> Pharo-project mailing list >> [email protected] >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project >> > > > _______________________________________________ > Pharo-project mailing list > [email protected] > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project _______________________________________________ Pharo-project mailing list [email protected] http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
