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 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.
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).
Thanks, both patches merged to trunk.
Sorry, I closed the wrong bug! Ignore my last comment.
(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.
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>
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} ?
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.