id summary reporter owner description type status priority milestone component version resolution keywords cc port 12048 RFE: Document all the code in the MacPorts base boeyms@… macports-tickets@… "I, and I suspect many others, find the MacPorts base difficult to understand because of the lack of documentation. While the filenaming is on the whole a reasonably good guide to which parts of the functionality are where, there seems to be little documentation in the code of what individual functions do (with what little there is usually being quite terse), and, more importantly, there is almost nothing in the way of higher-level descriptions of the way in which MacPorts works, the data structures on which it operates, and which parts of the API are public and which are private. The first priority, I think, would be just to document the source in any way, but a second goal should be to provide the means to generate separate code documentation from the source. The extant means for doing this with Tcl appear to be [http://www.oche.de/~akupries/soft/autodoc/ autodoc], [http://www.oklin.com/zdoc/] and [http://wiki.tcl.tk/5598 tcldoc] (there are more details about tcldoc [http://tcl.jtang.org/tcldoc/tcldoc/ here]). For a more minimal approach, the Tcl wiki has a [http://wiki.tcl.tk/10793 small example on how to generate Python-style docstrings from Tcl source] (it also appears [http://en.wikibooks.org/wiki/Programming:Tcl_Tcl_examples#Docstrings in the Tcl book on Wikipedia]). We could also devise a new approach, though that would obviously be a project in itself. Should we decide upon any of these, however, it should not be too difficult to convert any previous documentation to fit such tools; the main thing is that it really ought to be done to ease and speed development on the base code, both for those who currently work on it and to attract more developers to do so." enhancement new Normal base base documentation jmpp@… jberry@… boeyms@… landonf lperry cooljeanius larryv