4) Lack of any development documentation, guides and API specifications
Well, that's because I don't have time. =) I also tend to believe that well-written code is better documentation than half-written, out of date docs (which most such docs for opensource projects are).
I tend to agree that we need more documentation for Myth actually. I have just rejigged a lot of the audio stuff mainly so that I could build a Jack output layer for my own purposes, and also studied mythmusic quite a bit in order to tweak the audio there. However, it took a fair bit of effort to get to grips with all the subtle details of when stuff is called and why.
I have been thinking a bit about how best to pass on the knowledge gained to other people. For sure external documentation maintained seperately is hard to keep current (no questions there!!). Also I can hardly be accused of overdocumenting the code I produced...
I suspect that the best docs are those which are integrated into the code so that they have best chance of being maintained, and can then be used to automatically create external docs? I was intending to investigate Oxygen (sp?) which seems to be quite popular to see if I couldn't at least contribute some of that knowhow back for the benefit of someone else trying to maintain that stuff.
The docs I think I would have found useful are the overview docs. Something like how all the audio bits plug together. Descriptions of what the input and output params are and any dependencies (for example I have to keep looking up which audio functions take "bytes", which take "samples". Also should I call this "reset" function if I change something or not?). Class inheritance diagrams would also have been useful in Mythmusic because sometimes the concrete classes have slightly obscure names compared with the base classes (lots of grepping needed)
The other big area that I don't feel comfortable with is the gui stuff. Right now I really don't feel that I could just dive in and create some new screens or do some changes to the existing one without investing a fair bit of time trying to figure out the details. For example I would quite like to edit the TV playback page so that I can have some virtual categories under the "All programs" option that would be "By Date", "By Category", "By Length", etc so that I can easily drop in and see which Films, or documentaries I have to watch. I haven't invested much time in figuring out the details, but it didn't look like a totally trivial change?
Do you have any suggestions on how else we could document this stuff with the goal of getting this "big picture" stuff available? I suspect that Oxygen has been suggested in the past, but perhaps it isn't the best choice?
Anyway, please don't anyone interpret this as criticism of anything. I am just offering some comments on what I found tricky whilst doing some coding. Clearly I am also going to have to help resolving this if we can agree on a better way of doing things going forward...
Thanks for Mythtv
Ed W _______________________________________________ mythtv-dev mailing list [EMAIL PROTECTED] http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev
