[mythtv] MythTV: Isaac Tivo: > 100 tech guys
Ed Wildgoose
lists at wildgooses.com
Wed Dec 8 09:19:42 UTC 2004
>> 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
More information about the mythtv-dev
mailing list