On Feb 12, 2008 11:21 AM, Peter Bex <[EMAIL PROTECTED]> wrote: > > One of the problems I see is that there are other types of objects > > besides lambdas.
Everything should be able to have documentation comments (by which I mean S-exprs), not just lambdas. > Another problem is that docstrings are very limited in what you can put > in them. If you cram a tutorial in them, the source becomes unreadable > and if you keep it brief, where do you put the other docs? What's wrong with having longer docs be separate? What about coming up with a consensus on a path where such docs will be stored, so that within the documentation comments (which are part of the code) it's possible to make links to stuff like that? e.g. (see (href "eggs/myegg/tutorial")) would be analogous to a Doxygen @see directive. When the doc comments (s-exprs) are parsed and the real documentation is generated (HTML and whatever other forms) the links can be translated to full paths or relative paths, whatever works. And installing an egg should install the real documentation to a known path like /usr/share/doc/chicken/eggs/myegg. If all the documentation were in one place like that, we would not be needing to use the online documentation so much, and it would be possible to work without a network connection sometimes. (No doubt the bandwidth on callcc.org is much higher than it needs to be, just because of the lack of this.) A local index should be built too, or a local full-text search engine could be used, so that the search feature of the wiki is also replicated on every Chicken installation. Until we get around to that part, it would at least be possible to make do with whatever your usual local search engine is (Beagle, hyperestraier, swish++, mnogosearch etc.) Linux machines often have Apache configured so that http://localhost/doc goes to /usr/share/doc anyway. Some of them have search engines set up for local documentation already, too. _______________________________________________ Chicken-users mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/chicken-users
