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. On Aug 23, 2011, at 6:27 PM, eviljoel wrote: > Hello All, > > I think we should welcome this. I am finding it hard to get into the > ioquake3 source code partly due to the lack of documentation. > > More documentation in the code will help make ioquake3 more accessible > and will make the source code a more valuable learning tool. Also, as > long as the commenters do not change the format of the code and only > insert comments, merging and commit history will not be terribly > affected. > > We should definitely consider this. > > Sincerely, > eviljoel > > > On Tue, Aug 23, 2011 at 7:37 PM, <m...@rq3.com> wrote: >> Yeah, honestly, though it'd be a big change, it'd be a one-time thing to >> synch up and then you don't worry about it anymore except for >> comments/docs near code that's changing anyway. >> >> And yeah, ain't no one pay attention to the wiki unless they want to use >> it as a source for an article. >> >> My non-coder thoughts. >> >> >>>> On Tue, Aug 23, 2011 at 4:32 AM, uwe koch <spiro...@gmx.net> wrote: >>>>> On 22.08.2011 11:12, Thilo Schulz wrote: >>> >>>>> A patch would leave no piece of code untouched, this is a nightmare >>>>> from the >>>>> point of view of someone who regularly merges ioquake3 changes to his >>>>> project. >>> >>> Every ioq3 fork that I have seen is already a nightmare. I don't >>> think people are worried about making it easy to keep in sync. What >>> happened to that hg/git discussion over a year ago? >>> >>>> The documentation can live in seperate files, it doesn't have to be >>>> mingled with the code. >>> >>> The code and documentation should be mingled. Otherwise, it will get >>> out of sync. Additionally, you cannot generate as good of >>> documentation without modifying the code. Tools like doxygen are >>> designed to figure out as much of the structure and content of your >>> code as possible along with your manually entered comments. >>> >>>> I think the main problem is getting people to contribute. The code >>>> overview pages in the ioquake3 wiki are in bad shape because of lacking >>>> contributions, even tough editing a wiki page is dead easy. Compare that >>>> to the process of formatting your documentation in javadoc syntax, >>>> creating a patch file, filing it to bugzilla and having someone commit >>>> it. >>> >>> I don't want to edit a wiki because it can get out of sync with the >>> code. It's better having it along side the code. When people update >>> the code, they can fix any documentation that was impacted. >>> >>> If ioquake3 was using hg/git, end users could add documentation easily >>> and tell the ioquake3 developers to pull the changes. >>> >>>> In case this takes off, (as a fork, for starters?) I'd be happy to merge >>>> the stuff from http://soclose.de/q3doc/ >>> >>> Never heard of this. Thanks. >>> _______________________________________________ >>> ioquake3 mailing list >>> ioquake3@lists.ioquake.org >>> http://lists.ioquake.org/listinfo.cgi/ioquake3-ioquake.org >>> By sending this message I agree to love ioquake3 and libsdl. >>> >> >> _______________________________________________ >> ioquake3 mailing list >> ioquake3@lists.ioquake.org >> http://lists.ioquake.org/listinfo.cgi/ioquake3-ioquake.org >> By sending this message I agree to love ioquake3 and libsdl. >> > _______________________________________________ > ioquake3 mailing list > ioquake3@lists.ioquake.org > http://lists.ioquake.org/listinfo.cgi/ioquake3-ioquake.org > By sending this message I agree to love ioquake3 and libsdl. _______________________________________________ ioquake3 mailing list ioquake3@lists.ioquake.org http://lists.ioquake.org/listinfo.cgi/ioquake3-ioquake.org By sending this message I agree to love ioquake3 and libsdl.
