theora dev - Jun 2006 - libtheora API documentation

Hi,

The documentation for the libtheora API is a little bit sparse - for
example, information about whether yuv_buffer structs should be
managed by the user or the library is missing.  From talking to derf,
and from what I can see in the example files, the user allocates the
struct but not the luma/chroma buffers on decode; and the user
allocates both the struct and the luma/chroma buffers on encode.

I've made some small additions to the documentation explaining this.
Should I send these changes?  If so, do you have any guidelines for
patch format?

If it'll be useful, I may continue to add information to the
documentation.  Should I provide these additions incrementally, or
wait until I'm happy with the state of the documentation and provide a
large diff?

Thanks,
    -Shane Stephens

On 6/27/06, Shane Stephens <shane.stephens@gmail.com>
wrote:
> Hi,
>
> The documentation for the libtheora API is a little bit sparse - for
> example, information about whether yuv_buffer structs should be
> managed by the user or the library is missing.  From talking to derf,
> and from what I can see in the example files, the user allocates the
> struct but not the luma/chroma buffers on decode; and the user
> allocates both the struct and the luma/chroma buffers on encode.
>
> I've made some small additions to the documentation explaining this.
> Should I send these changes?  If so, do you have any guidelines for
> patch format?
Patches are always welcome. Documentation patches are _particularly_
welcome - we know that our documentation is often insufficient, so
help here is great. Thanks!

Generally, unified diffs are the preferred way to provide patches.

It's probably best to send what you have now, then updates when you've
got substantial improvements - no need to make people wait even longer
for this!

Mike