On Wed, Aug 24, 2011 at 5:24 AM, Zachary <[email protected]> wrote: > hg will come as soon as I find the time to enforce the change and agree with > Top Men (current svn contributors) on our switchover timeline. > > documentation alongside code does make sense, but for now it must be on the > wiki unless you know of some other documentation process or program which is > good and does not interfere with our SOP which is to not make sweeping > changes.
Once hg is setup, you could have a long lived branch for code documentation. It would never be committed into your master branch, but it could be kept in sync with the master. It wouldn't interfere with your SOP for the master branch but it would allow tools like doxygen to generate meaningful documentation. I think using a branch is better than the wiki because it can be kept in sync and it's compatible with doxygen. You could of course have the branch in SVN, but it's not as nice to pull in changes with full history. That's another aspect of hg vs. git that I think is worth considering. If you use git and a site like github, everyone can create public forks that you can pull changes from. If someone outside of your Top Men has a change, they can do the work in github and then tell Top Men to pull in the changes with full history. Since two of your Top Men don't appear to like generated documentation, you could delegate that responsibility to some community members. The delegated people can pull in documentation changes from the community and when they reach some stable point, they can tell your Top Men to pull in the changes to the ioquake3 branch. Or you could leave it as a fork. The only problem I can think of is if some project decided to fork from the documentation branch rather than master. Is there something like github for hg? It's not really a tool difference of hg vs. git but more of community difference. You can generate patches with full history in hg, but that's another step for both parties. The non-Top Men have to generate it and attach it to an email or bug report and refresh it every time it changes. The Top Men have to download the file and apply it manually. Or you have to assume that non-Top Men have setup public hg repository mirrors on their own which is unlikely. Here's an example I ran against r2148 with Doxygen. I turned off call graph, caller graph and inline sources. There are no comments of course but this is the default layout. The q3doc URL that was posted earlier was using a very old version of Doxygen and quake 3 source code. d05c864c8d3102ed6b6e6a4cf7a8611f2fb09c60 doxygen.tar.xz http://www.mediafire.com/?0n87yn099yuanl8 If you're only familiar with say javadoc, doxygen has many more features: Generate documentation, todo list, test list, bug list, deprecated list, optional inline source code browser (optionally strips doxygen comments leaving normal comments), inline HTML, mscgen message sequence diagrams, reference list, referenced list, call graph, caller graph, Xcode 3 docset, LaTeX formulas, DHTML search engine, support for external PHP search engine, include graph, included graph Output formats: HTML, Windows HTML Help, LaTeX, PDF, RTF, man pages, XML, perl mod, TAGS file _______________________________________________ ioquake3 mailing list [email protected] http://lists.ioquake.org/listinfo.cgi/ioquake3-ioquake.org By sending this message I agree to love ioquake3 and libsdl.
