[mythtv] MythTV: Isaac Tivo: > 100 tech guys

[Ed Wildgoose]

>>    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