Opened 14 years ago

Last modified 7 years ago

#12048 new enhancement

RFE: Document all the code in the MacPorts base

Reported by: boeyms@… Owned by: macports-tickets@…
Priority: Normal Milestone:
Component: base Version:
Keywords: base documentation Cc: jmpp@…, jberry@…, boeyms@…, landonf (Landon Fuller), lperry (Perry Lee), cooljeanius (Eric Gallager), larryv (Lawrence Velázquez)
Port:

Description

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.

Change History (19)

comment:1 Changed 14 years ago by boeyms@…

Cc: macports-dev@… added; macports-dev@… removed

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

comment:2 Changed 14 years ago by boeyms@…

Component: portsbase

comment:3 Changed 14 years ago by boeyms@…

Cc: jmpp@… jberry@… boeyms@… added; macports-dev@… removed

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 :-)

comment:4 Changed 14 years ago by jmpp@…

Cc: landonf@… added
Milestone: Needs developer reviewFeature Requests

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

comment:5 Changed 14 years ago by jmpp@…

Milestone: Feature RequestsMacPorts base enhancements

Milestone Feature Requests deleted

comment:6 Changed 14 years ago by nox@…

Priority: ImportantHigh
Version: 1.5

comment:7 Changed 14 years ago by nox@…

Milestone: MacPorts base enhancementsDocumentation

comment:8 Changed 14 years ago by 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...

comment:9 Changed 14 years ago by 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.

comment:10 Changed 14 years ago by afb@…

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

comment:11 Changed 14 years ago by 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.

comment:12 Changed 13 years ago by jmpp@…

Priority: HighNormal

comment:13 Changed 13 years ago by afb@…

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

comment:14 Changed 12 years ago by lperry (Perry Lee)

Cc: perry@… added

Cc Me!

comment:15 Changed 12 years ago by (none)

Milestone: Website & Documentation

Milestone Website & Documentation deleted

comment:16 Changed 9 years ago by cooljeanius (Eric Gallager)

Cc: egall@… added

Cc Me!

comment:17 Changed 8 years ago by larryv (Lawrence Velázquez)

Cc: larryv@… added

Cc Me!

comment:18 Changed 7 years ago by cooljeanius (Eric Gallager)

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

comment:19 in reply to:  10 Changed 7 years ago by 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?

Note: See TracTickets for help on using tickets.