[cairo] [PATCH] finalizing move to no-tmpl flavour of gtk-doc

[Rafał Mużyło]

On Wed, Nov 12, 2014 at 07:03:58PM -0800, Bryce Harrington wrote:
> This patch appears to be doing several distinct cleanups.
> 
> Deleting </para> from cairo-version.c - obviously good.
> 
>   * Compile-time
>   * ------------
> - * CAIRO_VERSION_STRING    Human-readable
> - * CAIRO_VERSION           Encoded, suitable for comparison
> + * #CAIRO_VERSION_STRING    Human-readable
> + * #CAIRO_VERSION           Encoded, suitable for comparison
> 
> I don't follow this bit; are the hashes just for doc markup?
> 

Indeed, it turns these two into links to their definitions.

> Dropping of tmpl - I'm not opposed to this but I'm not familiar with
> tmpl, can you give me background as to why it should be removed, and
> what the ramification is?  Is this what breaks check-doc-syntax?
>

Let me stress first, that I just apply some of the parts of gtk-doc
manual here.

For example, one of the recent ""fix" check-doc-syntax commits patches"
(caa4c9fdeb3aecd9a4288114e75d24ec931cd01b), did contain fixes for the
script warnings, but those were rather irrelevant for gtk-doc itself.
'**/' at the end is at best a style fix, as gtk-doc is interested only
in '/**' at the start (or is that something for the script itself ?).
Trying to document a *private* function (at least anywhere outside
the source) is a rather odd idea (and at best that only created
a stray file in xml/).

check-doc-syntax.sh runs on sgml templates.
There's that 40d6c580cd029f3d330ba28a7728ff36498920cb commit
(configure.ac: Do not generate template files when building docs), so 
- to a point - this has already been accepted in the past.
Given that commit, cairo shouldn't be generating the templates already.
It does only cause instead using the upstream gtk-doc.make it uses its
own copy to implement support for out-of-tree doc builds (which is
actually a very nice feature).

Now, add one more thing: in NEWS for gtk-doc 1.21, it has been clearly
stated, that the whole infra for generating the templates is planed to
be axed in the next release. Yeah, I know how it is with plans (the same
warning was in the previous release already, so they may reschedule again),
but that's still a pretty big warning, especially that the upstream
has discouraged the use of templates for a few years already.


> Removing references to cairo_stroke_to_path, I see the function is in
> cairo.c but #if 0'd out, commented "XXX: NYI".  While removing it from
> the documentation is certainly worthwhile if it'll never be implemented,
> let me ask the question - maybe we should implement it?
> 

:growl: Let's start with simple facts:
1. as it's '#if 0' it effectively doesn't exist
2. as it's not mentioned in doc/public/cairo-sections.txt, it does not
exist in the docs (which, given 1, is a good thing)
3. given 2, it serves only as a source of gtk-doc warnings

Not that such function wouldn't be useful in some cases, but sprinkling
references to non-existant functions gives you only *misleading* docs.