Documentation issue

[oneeyeman1 (Igor K)]

Hi, ALL,

I don’t know if this is the proper place to report, but…

The page https://developer.gnome.org/gtk3/stable/GtkTextTag.html#GtkTextAppearance, is missing the closing #endif.

Could someone please fix it?

And I sure hope that the actual code does not miss it…

Thank you.

[fmuellner (Florian Müllner)]

@oneeyeman1

The page https://developer.gnome.org/gtk3/stable/GtkTextTag.html#GtkTextAppearance , is missing the closing #endif.

It is also missing the trailing bits of the union.

@oneeyeman1

Could someone please fix it?

Not easily - API documentation is generated from the source code, so just fixing the online documentation means the error will be back when another GTK3 version is released.

Worse, it is unclear where the issue is - the struct in the sources is a bit dodgy (it’s different depending on whether __GI_SCANNER__ is defined), but valid; and gtk-doc (the tool to extract the documentation) correctly ignores everything below the /*< private >*/ magic comment, but doesn’t parse preprocessor macros.

Teaching gtk-doc about #ifdef and making it pick the “correct” branch would fix the issue, but it’s questionable whether the complexity outweighs the benefits here.

Still, opening a gtk-doc bug report looks like a good idea.

[FeRDNYC (Frank Dana)]

@fmuellner

gtk-doc (the tool to extract the documentation) correctly ignores everything below the /*< private >*/ magic comment

“Correctly” is perhaps open for debate, no? Currently it ignores everything following /*< private >*/, even in the outer scope, which may be as designed/intended, but it appears (based on this issue) that it’s not really ideal. Knowing nothing about gtk-doc (which… I don’t), I might have expected the generated source to look like this:

#ifdef __GI_SCANNER__
  /* The scanner should only see the transparent union, so that its
   * content does not vary across architectures.
   */
  union {
    GdkRGBA *rgba[2];
  };
#else
  GdkRGBA *rgba[2];
#if (defined(__SIZEOF_INT__) && defined(__SIZEOF_POINTER__)) && (__SIZEOF_INT__ == __SIZEOF_POINTER__)
  /* unusable, just for ABI compat */
#endif
#endif
};

(Or perhaps with that last, empty #if removed, ideally, since all of its contents were marked private.)

The generated docs might be more correct/readable if the private marker only extended until the end of the innermost enclosing block.

[FeRDNYC (Frank Dana)]

(I freely admit my “version” of the code doesn’t really make any more sense than what’s currently generated, but it’s at least valid syntax. …Well, assuming a union with only one member is valid.)

[ebassi (Emmanuele Bassi)]

@FeRDNYC

“Correctly” is perhaps open for debate, no? Currently it ignores everything following /*< private >*/ , even in the outer scope, which may be as designed/intended, but it appears (based on this issue) that it’s not really ideal.

The important thing to understand is that, unlike the gobject-introspection scanner which implements a C lexer, gtk-doc uses regular expressions to parse C code; this means that state is somewhat complicated to handle.

Yes, the /*< private >*/ trigram directive will ignore everything within the same structure declaration until the end. You can use /*< public >*/ to “undo” a private section, so in theory the whole thing could be done as:

  /* For the sad story of this bit of code, see
   * https://bugzilla.gnome.org/show_bug.cgi?id=711158
   */
#ifdef __GI_SCANNER__
  /* The scanner should only see the transparent union, so that its
   * content does not vary across architectures.
   */
  union {
    GdkRGBA *rgba[2];
    /*< private >*/
    guint padding[4];
    /*< public >*/
  };
#else
  GdkRGBA *rgba[2];
#if (defined(__SIZEOF_INT__) && defined(__SIZEOF_POINTER__)) && (__SIZEOF_INT__ == __SIZEOF_POINTER__)
  /* unusable, just for ABI compat */
  /*< private >*/
  guint padding[2];
  /*< public >*/
#endif
#endif

Or we could use the __GTK_DOC_IGNORE__ symbol that gtk-doc defines when parsing C code:

  /* For the sad story of this bit of code, see
   * https://bugzilla.gnome.org/show_bug.cgi?id=711158
   */
#if defined(__GI_SCANNER__) || defined(__GTK_DOC_IGNORE__)
  /* The scanner should only see the transparent union, so that its
   * content does not vary across architectures.
   */
  union {
    GdkRGBA *rgba[2];
    /*< private >*/
    guint padding[4];
  };
#else
  GdkRGBA *rgba[2];
#if (defined(__SIZEOF_INT__) && defined(__SIZEOF_POINTER__)) && (__SIZEOF_INT__ == __SIZEOF_POINTER__)
  /* unusable, just for ABI compat */
  /*< private >*/
  guint padding[2];
#endif
#endif

Or we could just give up on this structure being parseable with regular expressions, and provide its definition as a gtk-doc override:

<TYPEDEF>
<NAME>GtkTextAppearance</NAME>
typedef struct {
  /*< public >*/
  GdkColor bg_color; /* pixel is taken for underline color */
  GdkColor fg_color; /* pixel is taken for strikethrough color */

  /* super/subscript rise, can be negative */
  gint rise;

  guint underline : 4;          /* PangoUnderline */
  guint strikethrough : 1;

  /* Whether to use background-related values; this is irrelevant for
   * the values struct when in a tag, but is used for the composite
   * values struct; it's true if any of the tags being composited
   * had background stuff set.
   */
  guint draw_bg : 1;

  /* These are only used when we are actually laying out and rendering
   * a paragraph; not when a GtkTextAppearance is part of a
   * GtkTextAttributes.
   */
  guint inside_selection : 1;
  guint is_text : 1;
  GdkRGBA *rgba[2];
} GtkTextAppearance;
</TYPEDEF>

[FeRDNYC (Frank Dana)]

@ebassi

The important thing to understand is that, unlike the gobject-introspection scanner which implements a C lexer, gtk-doc uses regular expressions to parse C code

Say no more! Now I’m too impressed by the audacity of the exercise, to nitpick the execution.

That’s like announcing that you plan to sail from Boston to Paris on a broken 65" Samsung LCD TV, using a hard salami as a paddle.