Bug 82741

Summary: cairo 1.12.16: minor fixes to the docs
Product: cairo Reporter: Rafał Mużyło <galtgendo>
Component: generalAssignee: Chris Wilson <chris>
Status: RESOLVED FIXED QA Contact: cairo-bugs mailing list <cairo-bugs>
Severity: minor    
Priority: medium CC: nravi.n
Version: 1.12.16   
Hardware: All   
OS: All   
Whiteboard:
i915 platform: i915 features:
Attachments: minor fixes to the docs

Description Rafał Mużyło 2014-08-18 02:24:34 UTC
Created attachment 104780 [details] [review]
minor fixes to the docs

Attached patch makes following changes:
- removes references to not implemented cairo_stroke_to path
- undocuments not implemented cairo_set_opacity
- fixes build of cairo-version doc page
- makes one more step toward porting cairo docs to to no-tmpl flavour

Doesn't fix:
- cairo_device_t references cairo_egl_surface_create(), which is undocumented
- doc/public/check-doc-syntax uses tmpl files; not sure how/if that should be fixed (no-tmpl move was made on purpose, right ?)
- not fully synchronized with upstream gtk-doc changes
Comment 1 Ravi Nanjundappa 2014-08-18 04:05:50 UTC
Comment on attachment 104780 [details] [review]
minor fixes to the docs

Review of attachment 104780 [details] [review]:
-----------------------------------------------------------------

::: cairo-1.12.16-old/src/cairo.c
@@ -621,4 @@
>  
>  
>  #if 0
> -/**

I feel, we need to know the reason of this #if 0 statement, before undocumenting the cairo_set_opacity API.

@@ -1142,5 @@
>   * converted to a bevel.
>   *
>   * As with the other stroke parameters, the current line miter limit is
> - * examined by cairo_stroke(), cairo_stroke_extents(), and
> - * cairo_stroke_to_path(), but does not have any effect during path

AFAIK, cairo_stroke_to_path() is under #if 0 block. But at the same time, the comment also says it is NYI.
Comment 2 Rafał Mużyło 2014-08-29 09:45:44 UTC
In case of cairo_stroke_to_path, we only need to establish, that it's been there even on  cairo 1.0 branch and treat it  as 'oh, well, somebody commited their debug strings into upstream repo'.

As for cairo_set_opacity, it was commit 83bfd85a1378e61b8bdc3f554f5e07900311f61f and given its size, it just might be something that just accidentally got slipped in (and we're just removing it from gtk-doc scope anyway).
Comment 3 Bryce Harrington 2014-10-03 18:39:47 UTC
Thanks, both patches merged to trunk.
Comment 4 Bryce Harrington 2014-10-03 18:45:05 UTC
Sorry, I closed the wrong bug!  Ignore my last comment.
Comment 5 Rafał Mużyło 2014-10-03 23:10:53 UTC
(In reply to Bryce Harrington from comment #4)
> Sorry, I closed the wrong bug!  Ignore my last comment.

On the other hand though, if you're one of cairo devs, would you mind giving this bug a push, so that it gets into the upcoming release ?

Granted, this patch completely breaks that check-doc-syntax script, but there are strong hints it hasn't been used in awhile anyway.
Comment 6 Bryce Harrington 2017-11-06 20:23:22 UTC
I'll go ahead and take the removal of the doxygen for cairo_set_opacity().  I can't discern why it was disabled or what side effects re-enabling it might incur, but looks like it deserves future study if/when someone has the inclination.  Potentially it could be removed, as it's been 7 years with no complaints about its omission...

commit 35fccff6ec393ccca3d3ced79093ca491ce32df4
Author:     Bryce Harrington <bryce@osg.samsung.com>
AuthorDate: Mon Nov 6 12:09:53 2017 -0800
Commit:     Bryce Harrington <bryce@osg.samsung.com>
CommitDate: Mon Nov 6 12:18:37 2017 -0800

    Un-doxygen disabled cairo_set_opacity

    The cairo_set_opacity() routine has been disabled since 2010.  There
    appears to be support for it internally in the backend, so it is unclear
    why it is not enabled or what might break if it were re-enabled.  Given
    the lack of bug reports about its omission, it may be vestigal.  For
    now, just hide the doxygen for it to suppress warnings.  It may be worth
    deeper review to either re-enable it or remove it entirely.

    Reported-by: Rafał Mużyło (See fdo bugzilla #82741)
    Signed-off-by: Bryce Harrington <bryce@osg.samsung.com>
Comment 7 Rafał Mużyło 2017-11-06 21:45:42 UTC
Well, I've pretty much forgot about this, but as you did remind me, could you also push the part that documents CAIRO_VERSION{,_STRING} ?
Comment 8 Bryce Harrington 2018-04-03 00:52:42 UTC
Sure, pushed version fixes too:
To ssh://git.freedesktop.org/git/cairo
   12cb59b..dcafd9e  master -> master

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.