RFE: Document all the code in the MacPorts base

[boeyms@…]

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 ​autodoc, ​http://www.oklin.com/zdoc/ and ​tcldoc (there are more details about tcldoc ​here). For a more minimal approach, the Tcl wiki has a ​small example on how to generate Python-style docstrings from Tcl source (it also appears ​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.

[boeyms@…]

Whoops, fix the cc address so that macports-dev actually receives my RFE for documentation of the MacPorts code.

[boeyms@…]

Okay, so maybe the ticket won't post to macports-dev. I'll cc to James and Juan instead, and they can reallocate this to whomever they think would be most appropriate :-)

[jmpalacios (Juan Manuel Palacios)]

Would totally love to see a Doxygen like web documentation of the MacPorts API and layers. There is some documentation already on some of the source files, but most certainly not by far as much as we'd need to generate a good guide. If we do develop this, maybe we could link to the generated web pages on the "Internals" section of the MacPorts guide? Moving this to the "Feature requests" milestone.

-jmpp

[jmpalacios (Juan Manuel Palacios)]

Milestone Feature Requests deleted

[afb@…]

I added a new "tcldoc" port, and a "tcldoc" make target.

It has problems parsing a handful of files with e.g. braces embedded in strings, but that's easy to fix...

[afb@…]

BTW; I also tried "autodoc", but found the output thereof much less useful...

Not to mention that its installation had a few "weird" tcl lib dependencies, both of which were developed in like 2001 and didn't want to install nicely.

[afb@…]

So, what did you think of the tcldoc ? I don't need to put it up oneline, do I ?

[boeyms@…]

The tcldoc output looks promising. I haven't tried out autodoc or zdoc yet, despite having them lying around for ages. Perhaps some sample output should be put up somewhere, though, so that others can see it and comment on how useful they think it is.

[afb@…]

Added a "tcldox" make target, that uses doxygen with tcl-dox (as an alternative)

[lperry (Perry Lee)]

Cc Me!

[(none)]

Milestone Website & Documentation deleted

[cooljeanius (Eric Gallager)]

Cc Me!

[larryv (Lawrence Velázquez)]

Cc Me!

[cooljeanius (Eric Gallager)]

tcldoc documentation removed in r117902... I think that the focus has been on doxygen for automated documentation generation lately anyways...

[cooljeanius (Eric Gallager)]

Replying to afb@…:

So, what did you think of the tcldoc ? I don't need to put it up oneline, do I ?

That would have been nice (to put it up online), but it looks like it is a little too late for that now... maybe someone could do that for the doxygen output now instead?