Re: Updates API documentation for everything.
First, thanks to everybody who replied to my requests on Python, Smalltalk, and FORTH documentation tools. I will put the links you have given me into the document outlines linked from the OLPC Publications page, and at some point we can start expanding the outlines into draft documents. Further comments on these Wiki pages will be greatly appreciated. On Jan 1, 2008 3:50 PM, Mitch Bradley [EMAIL PROTECTED] wrote: Edward Cherlin wrote: Does anybody know of a documentation tool for Open Firmware, or for FORTH more generally? Exploring using 'words' and 'see' is fun up to a point if you're learning FORTH, but really doesn't cut it for supporting documentation. I presume that you have seen the tutorials at http://wiki.laptop.org/go/Forth_Lessons Yes. And I programmed in FORTH many years ago. The basic Open Firmware level is reasonably well documented - http://docs.sun.com/app/docs/doc/805-4436 http://firmworks.com/QuickRef.html That's what I mean. Thanks. The OLPC-specific stuff could certainly use some additional documentation. The source code for the OLPC-specific stuff has some amount of internal documentation that could be extracted. Each source file has a purpose comment at the top of the file, and many of the individual word definitions are preceded by a brief description. For example, the file cpu/x86/pc/olpc.fth begins with: purpose: Determine the board revision based on hardware and EC info and that file defines the word model-name$ as follows: \ Constructs a string like B4 or preB4 or postB4 : model-name$ ( -- model$ ) Many, but certainly not all, of the words that can plausibly be used interactively have brief description strings like that. Some words don't have brief descriptions in the source, and probably never will have them, based on the clarity of their names . For example, for the word bios-checksum-bad? ( -- flag ), I didn't feel compelled to write \ Returns true if the BIOS checksum is bad. The various xxx@ and xxx! words fall into that category, once you know the general pattern of @ and !. But even so, it would be nice to have a compendium of those words with English descriptions for easy reference. Exactly. It should be fairly easy to do. I'm not a big fan of automated documentation tools. They can help with the mechanics of extracting documentation strings from source code, but in my experience, such documentation is only marginally useful. The really hard part of understanding how something works is the contextual stuff - the circumstances under which it is appropriate to call a given function, how it fits together with related stuff, etc. Exactly. I have been working as an API Tech Writer for most of the last decade. Getting decent sample code out of developers has always been the hardest part of the job, and frequently I just had to write it myself. Phrases are more enlightening than individual words. Automated documentation extraction tends to describe individual trees, leaving you wondering about the overall shape of the forest. Projects that are set up for auto doc tools tend to have long structured comment blocks before every function. The individual fields are often extremely boring - like Outputs: none, and the overall size of the comment block takes up so much screen real estate that the actual code is lost among the boilerplate. Going back to the bios-checksum-bad? ( -- flag ) example, the usual tendency would be to say something obviously correct, and entirely pointless, like Returns a boolean flag that is true if the BIOS checksum is bad. What really should be said is something like: Conventional PC BIOSes checksum the CMOS RAM between indices 0x10 and 0x2d inclusive, storing the arithmetic sum as a 2-byte big-endian integer at indices 0x2e and 0x2f. bios-checksum-bad? tests that checksum. It is an implementation factor of init-bios-cmos, which ensures that said checksum is correct, fixing the checksum by zeroing that entire area if not. But of course people rarely write documentation that complete, for any number of reasons. Are you putting your hand up? That said, I really need to go through all the new OLPC code and at least add brief descriptions for all the top-level words. Ah. Evidently Yes. Thanks. Meanwhile, if anyone wants to look at the source code, the OLPC-specific bits are mostly collected in a few directories, primarily cpu/x86/build/olpc/ and dev/olpc/* The source tree is at http://openbios.org/Open_Firmware Very good. Thanks again, and Happy New Year. -- Edward Cherlin Earth Treasury: End Poverty at a Profit http://www.EarthTreasury.org/ The best way to predict the future is to invent it.--Alan Kay ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
On Jan 1, 2008 3:14 PM, M. Edward (Ed) Borasky [EMAIL PROTECTED] wrote: Edward Cherlin wrote: Does anybody know of a documentation tool for Open Firmware, or for FORTH more generally? Exploring using 'words' and 'see' Are you looking for automated documentation generation, or FORTH coding and documentation standards? I don't know about the former, but there is a well-established set of the latter, and given adherence, I'm sure the former is eminently possible. The FORTH community is fairly small (relative to, say, Python), and as a result, most FORTH programmers don't have much trouble reading the code of other FORTH programmers. Reading FORTH code is easy. Knowing which code to read requires experience. But I don't know about outsiders coming to FORTH from more traditional languages. :) Or no language. The children, in particular. I have long been of the opinion that you don't understand computing unless you have some grasp of hardware, and also of languages with quite different models of computation. At least LISP (well, Scheme or Logo), FORTH, Smalltalk, APL, and more conventional languages. Python definitely; C, C++, Java, only later when you won't mistake their design flaws and political compromises for received wisdom. Basically, languages that follow the dictum that Einstein apparently didn't say, but everybody thinks he should have: Everything should be made as simple as possible, but no simpler. We are in a good situation on the XO, and it's going to get better. -- Edward Cherlin Earth Treasury: End Poverty at a Profit http://www.EarthTreasury.org/ The best way to predict the future is to invent it.--Alan Kay ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
On Dec 30, 2007 10:20 AM, C. Scott Ananian [EMAIL PROTECTED] wrote: I have run the python documentation tool 'epydoc' on the contents of the joyride-1477 release. The results are here: http://dev.laptop.org/~cscott/joyride-1477-api/ Thanks. I was wishing for that. Can you do the other major builds also? I am running 653, and I keep hearing about Update.1. Does anybody know of a documentation tool for Open Firmware, or for FORTH more generally? Exploring using 'words' and 'see' This is probably the most up-to-date documentation available now for Sugar, the update and contents tools, rainbow, etc. I plan to integrate this into the joyride build process, so that there are always current API docs available. Thank you, thank you. When you can create a URL that will always go to the latest version, please add it to the Wiki. Comments welcome! And those of you who have not adequately documented your code, please do. Module-level comments in particular are very helpful, and often missing. --scott -- ( http://cscott.net/ ) ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel http://www.documentia.ca/lies.htm Biggest Lies Heard by Technical Writers * You should have a fully-functional product in your hands in plenty of time to complete your document. * The product's so intuitive, it practically writes the manual itself. * You won't be thought of as a nuisance by the SME's. They accept that you're a peer and respect that you have a job to do. * I'd make that more abstract. We'll make sure you have everything you need to get the job done. * As the tech writer at our company, you will have full, unrestricted access to the devolopment team's time and resources. etc. -- Edward Cherlin Earth Treasury: End Poverty at a Profit http://www.EarthTreasury.org/ The best way to predict the future is to invent it.--Alan Kay ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
Sorry. It got away from me. On Jan 1, 2008 2:11 PM, Edward Cherlin [EMAIL PROTECTED] wrote: On Dec 30, 2007 10:20 AM, C. Scott Ananian [EMAIL PROTECTED] wrote: I have run the python documentation tool 'epydoc' on the contents of the joyride-1477 release. The results are here: http://dev.laptop.org/~cscott/joyride-1477-api/ Thanks. I was wishing for that. Can you do the other major builds also? I am running 653, and I keep hearing about Update.1. Does anybody know of a documentation tool for Open Firmware, or for FORTH more generally? Exploring using 'words' and 'see' is fun up to a point if you're learning FORTH, but really doesn't cut it for supporting documentation. And what about Smalltalk/Etoys? This is probably the most up-to-date documentation available now for Sugar, the update and contents tools, rainbow, etc. I plan to integrate this into the joyride build process, so that there are always current API docs available. Thank you, thank you. When you can create a URL that will always go to the latest version, please add it to the Wiki. Comments welcome! And those of you who have not adequately documented your code, please do. Module-level comments in particular are very helpful, and often missing. --scott -- ( http://cscott.net/ ) ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel http://www.documentia.ca/lies.htm Biggest Lies Heard by Technical Writers * You should have a fully-functional product in your hands in plenty of time to complete your document. * The product's so intuitive, it practically writes the manual itself. * You won't be thought of as a nuisance by the SME's. They accept that you're a peer and respect that you have a job to do. * I'd make that more abstract. We'll make sure you have everything you need to get the job done. * As the tech writer at our company, you will have full, unrestricted access to the devolopment team's time and resources. etc. -- Edward Cherlin Earth Treasury: End Poverty at a Profit http://www.EarthTreasury.org/ The best way to predict the future is to invent it.--Alan Kay -- Edward Cherlin Earth Treasury: End Poverty at a Profit http://www.EarthTreasury.org/ The best way to predict the future is to invent it.--Alan Kay ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
Edward Cherlin wrote: Does anybody know of a documentation tool for Open Firmware, or for FORTH more generally? Exploring using 'words' and 'see' Are you looking for automated documentation generation, or FORTH coding and documentation standards? I don't know about the former, but there is a well-established set of the latter, and given adherence, I'm sure the former is eminently possible. The FORTH community is fairly small (relative to, say, Python), and as a result, most FORTH programmers don't have much trouble reading the code of other FORTH programmers. But I don't know about outsiders coming to FORTH from more traditional languages. :) ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
From: Edward Cherlin [EMAIL PROTECTED] And what about Smalltalk/Etoys? Not sure what level of doc you're seeking. If I misunderstood you, I apologize. Smalltalk's libraries are to a certain extent self-documenting in its browser, which is good because they vary depending on whatever you've synced from the central repositories. For Squeak overall, we have http://www.squeakbyexample.org. For how-to Etoys (the media/animation layer), I'm pretty impressed so far by the series of videos on http://www.waveplace.com/movies/ (speaking as somebody who doesn't care for non-written doc as a rule). ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
Edward Cherlin wrote: Does anybody know of a documentation tool for Open Firmware, or for FORTH more generally? Exploring using 'words' and 'see' is fun up to a point if you're learning FORTH, but really doesn't cut it for supporting documentation. I presume that you have seen the tutorials at http://wiki.laptop.org/go/Forth_Lessons The basic Open Firmware level is reasonably well documented - http://docs.sun.com/app/docs/doc/805-4436 http://firmworks.com/QuickRef.html The OLPC-specific stuff could certainly use some additional documentation. The source code for the OLPC-specific stuff has some amount of internal documentation that could be extracted. Each source file has a purpose comment at the top of the file, and many of the individual word definitions are preceded by a brief description. For example, the file cpu/x86/pc/olpc.fth begins with: purpose: Determine the board revision based on hardware and EC info and that file defines the word model-name$ as follows: \ Constructs a string like B4 or preB4 or postB4 : model-name$ ( -- model$ ) Many, but certainly not all, of the words that can plausibly be used interactively have brief description strings like that. Some words don't have brief descriptions in the source, and probably never will have them, based on the clarity of their names . For example, for the word bios-checksum-bad? ( -- flag ), I didn't feel compelled to write \ Returns true if the BIOS checksum is bad. The various xxx@ and xxx! words fall into that category, once you know the general pattern of @ and !. But even so, it would be nice to have a compendium of those words with English descriptions for easy reference. I'm not a big fan of automated documentation tools. They can help with the mechanics of extracting documentation strings from source code, but in my experience, such documentation is only marginally useful. The really hard part of understanding how something works is the contextual stuff - the circumstances under which it is appropriate to call a given function, how it fits together with related stuff, etc. Phrases are more enlightening than individual words. Automated documentation extraction tends to describe individual trees, leaving you wondering about the overall shape of the forest. Projects that are set up for auto doc tools tend to have long structured comment blocks before every function. The individual fields are often extremely boring - like Outputs: none, and the overall size of the comment block takes up so much screen real estate that the actual code is lost among the boilerplate. Going back to the bios-checksum-bad? ( -- flag ) example, the usual tendency would be to say something obviously correct, and entirely pointless, like Returns a boolean flag that is true if the BIOS checksum is bad. What really should be said is something like: Conventional PC BIOSes checksum the CMOS RAM between indices 0x10 and 0x2d inclusive, storing the arithmetic sum as a 2-byte big-endian integer at indices 0x2e and 0x2f. bios-checksum-bad? tests that checksum. It is an implementation factor of init-bios-cmos, which ensures that said checksum is correct, fixing the checksum by zeroing that entire area if not. But of course people rarely write documentation that complete, for any number of reasons. That said, I really need to go through all the new OLPC code and at least add brief descriptions for all the top-level words. Meanwhile, if anyone wants to look at the source code, the OLPC-specific bits are mostly collected in a few directories, primarily cpu/x86/build/olpc/ and dev/olpc/* The source tree is at http://openbios.org/Open_Firmware ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
On Dec 30, 2007 1:31 PM, Jeffrey Kesselman [EMAIL PROTECTED] wrote: In general it would be good if a docs could be made downloadable... I don't always have net access. Good point. When I integrate this into the build process, I'll be sure to .zip up the files as well. In the interim: http://dev.laptop.org/~cscott/joyride-1477-api.zip --scott -- ( http://cscott.net/ ) ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
