[gst-devel] various 0.9 questions

[Stefan Kost]

Hi,
Thomas Vander Stichele wrote:
> Hi,
> 
>>1.) Why is GST_PADDING in gst/gstconfig.h.in ?
> 
> Why not ? What would moving it help ?
the defines in gstconfig.h are conditionally set during the configure run. 
GST_PADDING is not dynamic. So IMHO it does not belong there. Its not a 
configurable item.
> 
> 
>>I'd like to move this out (e.g. gst/gst.h) and either
>>1a) document it or
>>1b) tell gtk-doc that it is private
> 
> 
> marking it private seems the correct thing to do.
moved to private scetion
> 
> 
>>While we're at it, whats about all the GST_DISABLE_XXX defines. Are they
>>of any interest for the developer (apart core). Should they get an
>>onliner doc comment or be made private?
> 
> 
> Aren't these adequately documented in configure --help ? Why do they
> need more ?
Grmpf. The question is just wheter they need API docs or not. I just moved them 
to the private section too.
> 
> 
>>2.) gst-plugins-base/gst/sine/gstsinesrc.c
>>static GstFlowReturn
>>gst_sinesrc_create (GstBaseSrc * basesrc, guint64 offset,
>>    guint length, GstBuffer ** buffer)
>>
>>Shouldn't it be GstClockTime offset ?
> 
> Don't think so - IIRC this is byteoffset.
Good question. Thats wahy wim should have put his docs into the source and not 
into unrelated and unlinked text files :(
> 
>>3.) GstMiniObject needs docs.
>>Some quick pointers in PWGs Porting sectionb of what to check if one was
>>using GstData before would be nice.
> 
> Yes; I think Ronald was writing a porting guide - Ronald ?
> 
> 
>>4.) marking new or changed stuff
>>Speaking of docs. New or changed API should have:
>>* Since: 0.9
>>as part of the docs. This will result in an extra index of these symbols.
> 
> 
> I'm not sure it does us much good at this point.  I completely see the
> value in this for projects like GLib, that are API-compatible across
> minor version increments, but we're not.  For 0.9 a lot of functions
> would be marked this way.  Maybe a good start would be to check first
> how many new methods there are.
> 
> I do completely see the value in this between micro versions, and I
> think I've done this a few times in the 0.8 series.  What do you think ?
>
For me this would be helpful to spot what parts have changed. Right now I just 
need to check which symbols have incomplete API docs. Then these are the one 
which have changed :(
 >
> As for the amount of undocumented stuff - totally, this needs to be
> fixed.  It was our hope people that were reading and following up on
> Wim's design notes sent to the list would result in some people adding
> gtk-doc strings.  I have done so a few times as I was going through a
> subsystem and learning about the changes.  I also added a few unit tests
> when I did this.  It's an excellent way for someone new to GStreamer's
> internals to get familiar with the code.
Thomas, I know that you care about the docs. I just wish wim and ds would do the 
same. I will try my best to go over wims notes again and update the real docs 
where I can. But this is really not the way this should happen. If one writes 
code, then write docs too. Otherwise the commit is faulty and incomplete.
It's so much harder and error prone to guess what the original author had in 
mind when adding/changing some part of the API.
> 
> Thomas
> 
Ciao
   Stefan