Commit Graph

28 Commits

Author SHA1 Message Date
Aleksander Morgado
ec6056e3ab glib-mkenums: allow optional 'since' tag
The glib-mkenums program allows generating code to handle enums/flags
with very different purposes. One of its purposes could be generating
per-enum/flag methods to be exposed in a library API, and while doing
that, it would be nice to have a way to specify in which API version
the enum/flag was introduced, so that the same version could be shown
in the generated API methods.

E.g. From the following code:

    /**
     * QmiWmsMessageProtocol:
     * @QMI_WMS_MESSAGE_PROTOCOL_CDMA: CDMA.
     * @QMI_WMS_MESSAGE_PROTOCOL_WCDMA: WCDMA.
     *
     * Type of message protocol.
     *
     * Since: 1.0
     */
    typedef enum { /*< since=1.0 >*/
        QMI_WMS_MESSAGE_PROTOCOL_CDMA  = 0x00,
        QMI_WMS_MESSAGE_PROTOCOL_WCDMA = 0x01
    } QmiWmsMessageProtocol;

The template would allow us to generate a method documented like this,
including the Since tag with the value given in the mkenums 'since' tag.

    /**
     * qmi_wms_message_protocol_get_string:
     * @val: a QmiWmsMessageProtocol.
     *
     * Gets the nickname string for the #QmiWmsMessageProtocol specified at @val.
     *
     * Returns: (transfer none): a string with the nickname, or %NULL if not found. Do not free the returned value.
     * Since: 1.0
     */
    const gchar *qmi_wms_message_protocol_get_string (QmiWmsMessageProtocol val);

Signed-off-by: Aleksander Morgado <aleksander@aleksander.es>
2020-05-14 17:00:54 +02:00
Aleksander Morgado
4d1132a945 docs,glib-mkenums: setup lists for enum/value trigraph extensions
Signed-off-by: Aleksander Morgado <aleksander@aleksander.es>
2020-05-14 17:00:46 +02:00
Nirbheek Chauhan
3732f9bd07 docs: Document generated headers caveats for genmarshal
And also link to the Meson FAQ that explains why this is needed so
people aren't just cargo-culting code.
2020-02-25 03:14:50 +05:30
Emmanuele Bassi
653e0f0813 Add links to Meson docs for genmarshal and mkenums 2020-02-24 16:14:33 +00:00
Emmanuele Bassi
83c13e52d5 docs: Mention Meson's gnome.mkenums_simple()
The mkenums_simple() function generates idiomatic GObject code, and
avoids templates and custom command line arguments.
2020-02-24 16:14:33 +00:00
Emmanuele Bassi
040803b34d Add example of using glib-mkenums with Meson
We're using Meson for GLib itself, and we recommend people to use it
for their own projects, so it would be good to have our documentation
present examples on how to use Meson with our tools.

Let's move the template example into its own section while we're at it,
since it's referenced by both Meson and Autotools examples.

Fixes: #1783
2020-02-24 15:46:35 +00:00
Emmanuele Bassi
15a4cf4d3f Ensure that we use @basename@ in the glib-mkenums docs
The documentation for @filename@ is not accurate either.
2020-02-24 15:08:49 +00:00
Philip Withnall
95e00c7581 docs: Various markup improvements to glib-mkenums man page
Signed-off-by: Philip Withnall <withnall@endlessm.com>
2019-03-04 11:14:22 +00:00
Nirbheek Chauhan
17316b2c16 glib-mkenums: Support reading @rspfiles for arguments
This is needed on Windows where the argument list can exceed the
maximum command-line length when lots of sources are passed to
glib-mkenums.
2018-12-04 16:16:00 +05:30
Simon McVittie
1830ebba91 Spelling: Fix spelling of "interpreted"
Detected by Debian's Lintian tool.

Signed-off-by: Simon McVittie <smcv@collabora.com>
2018-09-25 15:58:56 +01:00
Simon McVittie
214c991d5b Spelling: fix "every time"
Detected by Debian's Lintian tool.

Also fix the spelling of "linking" in one error message.

Signed-off-by: Simon McVittie <smcv@collabora.com>
2018-09-25 14:34:48 +01:00
Emmanuele Bassi
dcfa22549a docs: Small improvements to glib-mkenums man page
Clarify some typical usage of glib-mkenums and its substitutions.
2018-01-16 15:17:54 +00:00
Emmanuele Bassi
e6c3060144 docs: Drop references to Perl in glib-mkenums
The tool was ported to Python, but we should not mention the programming
language used, in case we port it to some other language in the distant
future.
2018-01-16 15:17:53 +00:00
Kouhei Sutou
4bdb012aae docs: Fix XML syntax error
Introduced by the following commit:

    commit cd97f93bf7
    Author: Emmanuele Bassi <ebassi@gnome.org>
    Date:   Fri Oct 13 16:05:07 2017 +0100

        docs: Update glib-mkenums man page

        We should show how to properly use glib-mkenums with Autotools, in
        the hope that fewer people will be caught cargo-culting rules written
        in the late '90s.

        https://bugzilla.gnome.org/show_bug.cgi?id=788948

https://bugzilla.gnome.org/show_bug.cgi?id=788978
2017-10-14 09:15:59 +01:00
Emmanuele Bassi
cd97f93bf7 docs: Update glib-mkenums man page
We should show how to properly use glib-mkenums with Autotools, in
the hope that fewer people will be caught cargo-culting rules written
in the late '90s.

https://bugzilla.gnome.org/show_bug.cgi?id=788948
2017-10-13 18:14:57 +01:00
Matthias Clasen
540374c80e Document --output option of glib-mkenums 2016-10-12 18:01:37 -04:00
Sébastien Wilmet
66ef10eec9 docs: syntax highlighting for the code examples
In the sections Concepts, Tools and Tutorial.

https://bugzilla.gnome.org/show_bug.cgi?id=736914
2014-09-26 23:36:26 +02:00
Matthias Clasen
794401c0a2 Document all glib-mkenums placeholders
The @ENUMPREFIX@ placeholder was missing in the man page.
2013-05-04 21:08:18 -04:00
Matthias Clasen
08dd0f246a docs: Improve man page consistency
Make Options sections refsect1 instead of refsect2, and use
uppercase for argument names. Also add a product name, and
shorten some argument names.
2012-08-03 23:36:45 -04:00
Dan Winship
f9c2362e43 glib-mkenums: add --identifier-prefix and --symbol-prefix args
Allow passing --identifier-prefix and --symbol-prefix to glib-mkenums,
with the same meanings as in g-ir-scanner, to allow fixing up the enum
name parsing globally rather than needing to add a /<* *>/ override to
each enum.

https://bugzilla.gnome.org/show_bug.cgi?id=661797
2011-10-28 18:04:28 -04:00
Dan Winship
78a0dbd853 docs: don't refer to a deprecated glib-mkenums flag
Refer to the new flag instead

https://bugzilla.gnome.org/show_bug.cgi?id=661797
2011-10-28 18:04:28 -04:00
Ryan Lortie
62c0454b34 documentation for glib-mkenums @valuenum@ 2010-05-14 01:55:46 +02:00
Matthias Clasen
61a5692fa1 Man page tweaks
Add enough info to keep the docbook stylesheets from embedding
FIXMEs in the formatted output.
2010-04-16 20:43:53 -04:00
Christian Persch
18e0bcf02f Add @basename@ substitution to glib-mkenums
Move man page addition to the right place. Bug #587307.
2009-07-03 21:20:11 +02:00
Matthias Clasen
d75bbbb124 Fix some formatting problems. 2005-08-15 18:45:27 +00:00
Stepan Kasal
0169468c8c Fix typos: invokation -> invocation. 2005-08-10 10:46:55 +00:00
Murray Cumming
10bacd6058 Added a lowercase_name option, to be used next to the enum declaration,
2003-12-30  Murray Cumming  <murrayc@usa.net>

        * gobject/glib-mkenums.in: Added a lowercase_name option, to be used
        next to the enum declaration, where the flag option is already used,
        when it is not possible to guess where to put the underscores in the
        _get_type() function name, for instance for GNOMEVFSURIHide.
2003-12-30 10:42:57 +00:00
Matthias Clasen
54f796b1b6 New macros to check for XML catalog contents and path, borrowed from
2003-06-17  Matthias Clasen  <maclas@gmx.de>

	* acinclude.m4 (JH_PATH_XML_CATALOG, JH_CHECK_XML_CATALOG): New
	macros to check for XML catalog contents and path, borrowed from
	gtk-doc.
	* configure.in: New option --enable-man to enable regeneration of
	man pages from Docbook, if the necessary tools are found.

	* gobject/Makefile.am: Add rule to regenerate man pages from
	Docbook.
	(man_MANS): Add glib-mkenums.1, glib-genmarshal.1 and gobject-query.1.
	(content_files): Add glib-mkenums.xml, glib-genmarshal.xml and
	gobject-query.xml.

	* gobject/glib-mkenums.xml:
	* gobject/glib-genmarshal.xml:
	* gobject/gobject-query.xml: New refentries.

	* gobject/glib-mkenums.1:
	* gobject/glib-genmarshal.1:
	* gobject/gobject-query.1: Man pages generated from the .xml
	sources.

	* gobject/gobject-docs.sgml: Include glib-mkenums.xml,
	glib-genmarshal.xml and gobject-query.xml.

	* glib/Makefile.am: Add rule to regenerate man pages from
	Docbook.
	(man_MANS): Add glib-gettextize.1.
	(content_files): Add glib-gettextize.xml.

	* glib/glib-gettextize.xml: New refentry.

	* glib/glib-gettextize.1: Man page generated from the .xml source.

	* glib/glib-docs.sgml: Include glib-gettextize.xml.
2003-06-17 23:08:37 +00:00