blob: e42d3ee81d2cff5b1f97d47d0ba7d87a17cb9ca3 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Writing API docs: GObject Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="GObject Reference Manual">
<link rel="up" href="pt03.html" title="Part V. Related Tools">
<link rel="prev" href="tools-refdb.html" title="Debugging reference count problems">
<link rel="next" href="api-index-full.html" title="Index">
<meta name="generator" content="GTK-Doc V1.25.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="pt03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="tools-refdb.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="api-index-full.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="tools-gtkdoc"></a>Writing API docs</h2></div></div></div>
<p>The API documentation for most of the GLib, GObject, GTK+ and GNOME
libraries is built with a combination of complex tools. Typically, the part of
the documentation which describes the behavior of each function is extracted
from the specially-formatted source code comments by a tool named gtk-doc which
generates DocBook XML and merges this DocBook XML with a set of master XML
DocBook files. These XML DocBook files are finally processed with xsltproc
(a small program part of the libxslt library) to generate the final HTML
output. Other tools can be used to generate PDF output from the source XML.
The following code excerpt shows what these comments look like.
</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="comment">/**</span>
<span class="comment"> * gtk_widget_freeze_child_notify:</span>
<span class="comment"> * </span><span class="type">@widget</span><span class="comment">: a #GtkWidget</span>
<span class="comment"> * </span>
<span class="comment"> * Stops emission of "child-notify" signals on </span><span class="type">@widget</span><span class="comment">. The signals are</span>
<span class="comment"> * queued until gtk_widget_thaw_child_notify() is called on </span><span class="type">@widget</span><span class="comment">. </span>
<span class="comment"> *</span>
<span class="comment"> * This is the analogue of g_object_freeze_notify() for child properties.</span>
<span class="comment"> **/</span>
<span class="type">void</span>
<span class="function"><a href="http://developer.gnome.org/gtk3/GtkWidget.html#gtk-widget-freeze-child-notify">gtk_widget_freeze_child_notify</a></span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GtkWidget</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">widget</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="symbol">...</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p>
</p>
<p>
Thorough
<a class="ulink" href="https://developer.gnome.org/gtk-doc-manual/stable/" target="_top">documentation</a>
on how to set up and use gtk-doc in your project is provided on the
<a class="ulink" href="https://developer.gnome.org/" target="_top">GNOME developer website</a>.
</p>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.25.1</div>
</body>
</html>