Developer documentation
#1
I've been reading through a fair amount of the XBMC code lately, to understand various aspects of how things work (mainly scrapers and addons), and it struck me that it might be helpful to put some of this information in the wiki. There is the development notes page, but it doesn't have these sorts of documents. There is also a nice 10,000 foot view of the architecture in the Wikipedia article.

For example (just an example - please discuss the content of the example, if incorrect, in another thread): how is fan art for a movie stored? In the database, it's stored as an XML chunk in the movie table (column c20 as it happens, although an article on the topic should just point to the table schema). The XML chunk is in the form <fanart><thumb preview="link to preview image">link to full-size image</thumb>...</fanart> (as returned by the scraper, and I'd link to Dev:Scraper here in the hope that later I or someone else would write it). I believe the first item in the list is shuffled to become the "current" fan art.

Fan art is cached to the video thumb directory under Fanart/crc32.tbn, where crc32 is the 8-character padded hex representation of the Ethernet-style CRC32 of the lowercased absolute filename of the movie. (Unfortunate side-effect of that is that moving the movie loses the fan art etc.; I built a small Python program to update the database and thumbnails based on file moves.) If the file is missing, XBMC will attempt to generate a thumb by extracting a frame from the movie (and it would be nice if that could be turned off with an advanced setting... patch may be offered to do that at some point, because they look so bad crammed into "cover" style images, take time/CPU to generate, and for me, will be replaced anyway).

I don't believe this belongs on the main Fanart page since it's not useful to most non-developers. Perhaps a "Dev:" prefix could be used for this sort of documentation, e.g. "Dev:Fanart".

What I am not proposing is that function-level documentation be done in the wiki; that rightly belongs in comments (or just clearly written code). I'm suggesting higher-level documentation - "what", not "how" - of the various parts of XBMC, that would be useful to developers seeking to understand the code (or just find the right location to look at) in order to fix bugs or add features. I'm also not suggesting that everything be documented at once, but rather as people either take the time to discover how something works, or, if they wrote it and feel like making a Dev page at some point.

Another danger is that the pages will get out of sync with respect to the code. That's OK; hopefully they won't be too badly so, since they're higher level than mere implementation. It would be nice if devs update these when the code changes, but it's unrealistic to expect that it will always happen. "Last update" dates will give a clue as to how recent the doc is, and even an out-of-date architecture doc can provide useful information.

I realize I can just log in to the wiki and start creating pages, but I'd like to get some feedback about the idea first.
Reply
#2
not many devs touch the WIKI as far as I have seen. The idea´s mostly stay an idea until some actually implements them. Actually, except the skinning section, the WIKI gets more and more out of sync with the actual state of code. So in general, you can say I second efforts to improve the WIKI...
Reply

Logout Mark Read Team Forum Stats Members Help
Developer documentation0