However, can we agree on the best way to do it first? I think doxygen (is that right now?) might be a promising move? I would prefer to get a steer from Isaac first though on how we are going to do this going forward.
I would thoroughly recommend Doxygen as a tool. I've used it in quite a few C++ projects before and find it invaluable when working in a team. If you've only got a small project then it's a bit overkill, but with, and I quote ">100 other people who make it possible" working on Myth and trying to hack the source to make it better, more efficient, more featurful and less buggy!
I even use Doxygen on my PHP projects now too (some of which are pretty huge), and it works like a charm. It has it's bugs too, but nothing too crazy and it can usually be worked around. I think the C++ doc generation side is far more stable than the PHP tho', as I don't recall any major issue when using it a couple of years ago for that!
Having also recently hacked about with MythMusic (and another patch coming soon), I have to concur with Ed Wildgoose that class inheritence diagrams would have been great. And more detailed documentation of the sometimes bizarrly named variables would be good too. Class inheritence can be generated just by firing up doxygen, but it only really comes into it's own with structured comments.
My recent Metadata patch probably had a few doxygen comments in the new classes I created. I almost do this automatically when I write code now, and I actually meant to strip them out before supplying the patch (as I thought they had been previously frowned upon), but forgot!
Isaac: Final word?
I don't want to speak out of turn or on Isaac's behalf, but IIRC the main issue was that Doxy comments can be quite large and take up a fair amount of screen real estate when editing your code.
I agree but I feel that the benefits far outweigh this disadvantage. I've just started using Eclipse as my IDE for development and the CDT project for C/C++ development has many useful functions.
IIRC, I think it does block comment folding, which means that it can basically turn a 10 line comment into a single line with a little + next to it. Perhaps using and IDE/Editor with such capabilities would work round that objection for many people?? (I know Eclipse can be slow/buggy, but there are others with similar features I'm sure, and Eclipse seems mostly fine for me).
Of course, if Doxygen was adopted, there would be the question of which style of commetns to use!! I've used both Qt style and JavaDoc style, and switched from one to the other at one point to get round indentation bugs in XEmacs!!! Seeing as Myth is Qt based I sps it makes sense to use Qt style!
As a companion to this, would some formal, written-down coding standards be a good idea? We had some a while back that were really good. It covered things like class named (TitleCaseNoUnderscores), local variables (lower_case_underscores), member variables (mTitleCasePrefixedWithM), and method/function arguments (titleCaseInitialDropCap) etc. etc. It made development very easy. At the moment when I read stuff in MythMusic, it is sometime hard to know at a glance with variables are local ones, which are member variables etc., so when working on large projects with multiple developers this can be a godsend!
I can't find the original file we used, but a quick look at this:
http://www.possibility.com/Cpp/CppCodingStandard.html and it seems to fit what I usually do. I especially like " 6 Phases of a Project (joke)" and " Flow Chart of Project Decision Making (joke)" but the real info starts at section 3.
I'm not suggesting everything gets changed to conform, just that there is a clear strategy for going forward. If someone wants to apply this to existing code then fine, but perhaps they can make their change using e.g. a sed script that then gets posted onto the mailing list along with their patch to let people with other, uncommited patches easily update their code!!
Perhaps I'm throwing too much in the melting pot here? One step at a time is probably better.
I vote for Doxygen.
All the best and thanks for everyones' efforts.
Col.
--
+------------------------+ | Colin Guthrie | +------------------------+ | [EMAIL PROTECTED] | | http://colin.guthr.ie/ | +------------------------+
_______________________________________________ mythtv-dev mailing list [EMAIL PROTECTED] http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev
