[gst-devel] improving plugin docs

[Stefan Kost]

hi,

I was working a bit on plugin docs lately. Good news is that with  
recent gtk-doc their nicely cross-reffed and also local baseclasses  
showup.

I have also some ideas to make it more automated, but that needs well tested.

Unfortunately there are also some issues:

1.) Most elements/plugins would not need a header. gtk-doc is for  
documenting the public interface and that is header + introspection.  
Now if we list the c-sources insteader of headers in Makefile.am it  
somewhat works, but creates a lot of false positives as there is a  
lots of definitely non public stuff found.

a) Creating (uninstalled) headers with the Object, ObjectClass structs  
and the defines fixes that but is ugly.

b) I could make gtk-doc scann for some special comments like /**  
gtk-doc off */ and /** gtk-doc on */. Other people have asked for  
something like this too.


2.) Some plugins have local object (e.g. videomixerpad). That should  
somehow appear in the docs as one needs to know that there is xpos,  
ypos, zorder and alpha properties there.

a.) Again factoring that out, would fix it.


better ideas welcome :)

Stefan