[gst-devel] questions about examples in plugin docs

[Stefan Kost]

Hi Thomas,

Thomas Vander Stichele wrote:
> Hi everyone,
> 
> http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/
> 
> On that page, both the "goom" and "level" element come with an example.
> Goom comes with a sample -launch line; I think we all can agree that's a
> good idea to have when it makes sense.
 >
Exactly e.g for the level element its not obvious how to get the level-data.
> 
> For some elements, that doesn't make sense.  Level for example is put in
> a pipeline and generates messages.  While it is possible to see them
> with gst-launch, it doesn't really explain you how to interpret the
> messages you get.  In those cases, a sample application makes sense.
> The docs for level have such an example.
> 
> On to the questions:
> 
> - does it make sense to put this example in the docs ? Is it not too
> long ?
> - Where should this example code be written ?
>   - in the element's .c file as comments ?
>   - in a separate .c file in the element's directory ?
>   - in a separate .c file in some top-level examples/ ?
> - What license should we slap on all of our example code ?
 >
I find sample code as part of the long-description not too long. Just to let you 
know, I plane to add folding to gtk-doc output. Then one can collaps the example 
and expand them on demand.
Have you tried to xinclude them into the docs? I'll try this locally later today 
and tell you if it works.
> 
> No matter where we would store the example code, I'd extract and build
> it as part of make check just like our manual examples, to make sure the
> examples stay current.
> 
> Let me know what you think,
> Thomas
>