[cairo] [PATCH] doc: fix some broken references

[Andrea Canciani]

On Thu, Dec 30, 2010 at 11:01 AM, Maarten Bosmans <mkbosmans at gmail.com> wrote:
> 2010/12/29 Andrea Canciani <ranma42 at gmail.com>:
>>> Am 28.12.2010 13:50, Maarten Bosmans wrote:
>>>> This fixes some obvious mistakes in the docs.
>>
>> The attachment is a patch that should probably be merged with yours.
>
> Attached is a new version of my patch and a modified version of yours,
> with duplicate changes removed
>
>> Cairo docs would use some more love and I have a couple of items in my
>> TODO list, but I haven't fixed them yet.
>
> Any suggestions? I was thinking of adding some more cross references
> ('see also' links) between relevant functions.

Straight from my TODO list:
 - document filtering, gradients, get_data/flush/mark_dirty

We should document the definition of the gradients (or at least give a
reference to the PDF specification aka ISO32000, where their definition
is mathematically sound and detailed enough).

cairo_image_surface_get_data() should reference cairo_surface_flush(), which
must be called before reading/writing data, and cairo_surface_mark_dirty(),
which must be called if the content of the data has been modified.
Similar functions in other backends (cairo_win32_surface_get_dc,
cairo_win32_surface_get_image, ...) should receive a similar treatment.

cairo_filter_t and cairo_extend_t would use a more complete definition
(what does each extend mode mean for gradients, expecially when the
stops don't cover the whole 0..1 range? etc etc)

>
>> In particular, if you are knowledgeable about gtk-doc, could you have a
>> look at https://bugs.freedesktop.org/show_bug.cgi?id=28060 ?
>
> It's a gtk-doc bug, solved now. What's the procedure for getting
> updated documentation on the website?

It gets updated as part of the release process.

>
>> I hope someone who knows how the remaining brokenness should be
>> fixed will speak up, because I'm unable to add anything useful to what
>> Uli already said.
>
> As per comments of Uli I changed the references xcb functions. Gtk-doc
> still complains because the new functions from egl and xcb are not
> documented, but at least the docs point to functions that exist within
> the cairo codebase.

They are not supported backends, so it is probably ok (at least until
we add a section for unsupported backends, as you suggested in the
other thread).

>
>> Thank you for your patch, I'll try to make sure it doesn't just get lost
>> in the ML ;)
>>
>> Andrea
>
> Maarten
>