[alsa-devel] [PATCH] 1/2 alsa-python: API coverage documentation tool

[Aldrin Martoq]

HG Log:
-------
Added python tool of alsa-lib C API coverage for alsa-python binding.


Description:
------------

The following patch is a python tool that shows how much of the
asoundlib API is being covered by the alsa-python binding. It works by
parsing the C source code and comparing with the official Doxygen
documentation from alsa website.

It will help the following users:
- alsa-python developers: know how is mapped the original C API, so
which python function/variable may be used.
- python binding developers: know how much of the C API is covered. It
could help for mistakes (free() instead of using
snd_ctl_card_info_free), know what is missing, and statistic interest ;)



Sample output:
--------------

Functions
---------
1   const char* snd_asoundlib_version ( void )
        Returns the ALSA sound library version in ASCII format.
          => Used in    :     alsacard.c: asoundlib_version

Defines
-------
N/A #define SND_CONTROL_DLSYM_VERSION _dlsym_control_001
        dlsym version for interface entry callback
          **** NOT AVAILABLE/USED SND_CONTROL_DLSYM_VERSION ****
2   #define SND_CTL_ASYNC
        Async notification (flag for open mode)
          => As constant:  alsacontrol.c: open_mode["ASYNC"]
          => As constant: alsahcontrol.c: open_mode["ASYNC"]
1   #define snd_ctl_card_info_alloca ( ptr )
        allocate an invalid snd_ctl_card_info_t using standard alloca
          => Used in    :  alsacontrol.c: pyalsacontrol_cardinfo


Stats:
------

After every section, the program shows some stats about usage. This is
the current usage of each doxygen module:

Global defines and functions  
 16 missing ( 94%)   0 excluded (  0%) of  17 total (  6% covered).
Error handling                
  9 missing ( 90%)   0 excluded (  0%) of  10 total ( 10% covered).
Control Interface             
137 missing ( 53%)   0 excluded (  0%) of 257 total ( 47% covered).
High level Control Interface  
 21 missing ( 46%)   0 excluded (  0%) of  46 total ( 54% covered).
Setup Control Interface       
  4 missing (100%)   0 excluded (  0%) of   4 total (  0% covered).
MIDI Sequencer                
 25 missing ( 61%)   7 excluded ( 17%) of  41 total ( 39% covered).
Sequencer Client Interface    
 15 missing ( 35%)  14 excluded ( 33%) of  43 total ( 65% covered).
Sequencer Port Interface      
 48 missing ( 74%)   6 excluded (  9%) of  65 total ( 26% covered).
Sequencer Port Subscription   
  3 missing (  7%)  15 excluded ( 33%) of  46 total ( 93% covered).
Sequencer Queue Interface     
 58 missing ( 84%)   0 excluded (  0%) of  69 total ( 16% covered).
Sequencer Event API           
 42 missing ( 93%)   0 excluded (  0%) of  45 total (  7% covered).
Sequencer Miscellaneous       
  0 missing ( N/A)   0 excluded ( N/A) of   0 total ( N/A covered).
Sequencer Event Type Checks   
  7 missing ( 23%)   0 excluded (  0%) of  30 total ( 77% covered).
Sequencer Event Definitions   
 35 missing ( 40%)   0 excluded (  0%) of  87 total ( 60% covered).
Sequencer Middle Level Interfa
 38 missing ( 78%)   0 excluded (  0%) of  49 total ( 22% covered).
Sequencer event <-> MIDI byte 
 11 missing (100%)   0 excluded (  0%) of  11 total (  0% covered).
Mixer Interface               
 44 missing ( 75%)   0 excluded (  0%) of  59 total ( 25% covered).
Simple Mixer Interface        
 14 missing ( 18%)   0 excluded (  0%) of  78 total ( 82% covered).


Cheers!


-- 
Aldrin Martoq <amartoq at dcc.uchile.cl>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: doc-alsa-python-coverage
Type: text/x-patch
Size: 25733 bytes
Desc: not available
Url : http://mailman.alsa-project.org/pipermail/alsa-devel/attachments/20080307/a152f0b0/attachment-0001.diff