gnome-devel-docs 3.28.0-1 / usr / share / help / el / programming-guidelines / documentation.page

<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:xi="http://www.w3.org/2003/XInclude" type="topic" id="documentation" xml:lang="el">

  <info>
    <link type="guide" xref="index#general-guidelines"/>

    <credit type="author copyright">
      <name>Federico Mena-Quintero</name>
      <email its:translate="no">federico@gnome.org</email>
      <years>2013</years>
    </credit>
    <credit type="author copyright">
      <name>Philip Withnall</name>
      <email its:translate="no">philip.withnall@collabora.co.uk</email>
      <years>2015</years>
    </credit>
    <credit type="author copyright">
      <name>Η ομάδα GTK+</name>
    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>

    <desc>Adding documentation to libraries and APIs</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Ελληνική μεταφραστική ομάδα GNOME</mal:name>
      <mal:email>team@gnome.gr</mal:email>
      <mal:years>2016</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Θάνος Τρυφωνίδης</mal:name>
      <mal:email>tomtryf@gnome.org</mal:email>
      <mal:years>2016</mal:years>
    </mal:credit>
  </info>

  <title>Τεκμηρίωση</title>

  <synopsis>
    <title>Σύνοψη</title>

    <list>
      <item><p>
        Use gtk-doc with up-to-date settings for API documentation.
        (<link xref="#gtk-doc"/>)
      </p></item>
      <item><p>
        Use XML entities for including external symbols into the documentation.
        (<link xref="#build-system"/>)
      </p></item>
      <item><p>
        Use a consistent, standard, table of contents for all API documentation
        to maintain familiarity. (<link xref="#standard-layout"/>)
      </p></item>
      <item><p>
        Use <cmd>gdbus-codegen</cmd> to generate D-Bus API documentation to
        include in the gtk-doc build. (<link xref="#dbus-api"/>)
      </p></item>
      <item><p>
        Add introspection annotations to all API documentation.
        (<link xref="#introspection-annotations"/>)
      </p></item>
      <item><p>
        Add <code>Since</code> lines to all API documentation.
        (<link xref="#symbol-versioning"/>)
      </p></item>
      <item><p>
        Enable gtk-doc tests. (<link xref="#keeping-up-to-date"/>)
      </p></item>
    </list>
  </synopsis>

  <section id="gtk-doc">
    <title>gtk-doc</title>

    <p>
      The preferred documentation system for GNOME libraries is <link href="http://www.gtk.org/gtk-doc/">gtk-doc</link>, which
      extracts inline comments from the code to let you build a <link href="http://docbook.org/">DocBook</link> document and collection of HTML
      pages.  These can then be read in
      <link href="https://wiki.gnome.org/Apps/Devhelp">Devhelp</link>.  A lot of
      GNOME’s infrastructure is built to handle with documentation written using
      gtk-doc.
    </p>
  </section>

  <section id="build-system">
    <title>Σύστημα δόμησης</title>

    <p>
      To integrate gtk-doc into a project’s build system, follow the
      <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup.html.en">
      instructions in the gtk-doc manual</link>. Note that while the
      <file>sections.txt</file> file is automatically generated the first time
      gtk-doc is run, it is not generated subsequently, and should be kept up to
      date manually. It should also be
      <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup_vcs.html.en">
      in version control</link>.
    </p>

    <p>
      gtk-doc’s <code>no-tmpl</code> flavour should be used, and XML mode should
      be used instead of SGML. (tmpl mode and SGML are both outdated and slower
      than XML.)
    </p>
    <p>
      If the package version is needed to be substituted into the documentation,
      create a file named <file>docs/version.xml.in</file>, containing:
    </p>
    <code>@PACKAGE_VERSION@</code>
    <p>
      Add it to <code>AC_CONFIG_FILES</code> in <file>configure.ac</file>, then
      include it into the main documentation file (<file>*-docs.xml</file>)
      using: <code>&lt;!ENTITY version SYSTEM "version.xml"&gt;</code> in the
      <code>DOCTYPE</code> at the top of the document. The package version can
      then be used inline as <code>&amp;version;</code>.
    </p>
  </section>

  <section id="standard-layout">
    <title>Τυπική διάταξη</title>

    <p>
      Using a standard layout for the table of contents, sections, appendices,
      etc. means the same <file><var>project-name</var>-docs.xml</file> template
      can be reused with few changes between projects. It also means the
      documentation layout is similar across all projects, making it more
      familiar to developers.
    </p>

    <p>
      The following layout is suggested:
    </p>
    <listing>
      <title><file><var>project-name</var>-docs.xml</file></title>
      <desc>A template top-level gtk-doc file for a project</desc>
      <code mime="application/docbook+xml"><xi:include href="example-docs.xml" parse="text"/></code>
    </listing>
  </section>

  <section id="licensing">
    <title>Licensing</title>
    <p>
      It is important to make the license used for API references clear,
      especially if they contain code examples which could be copied around.
    </p>

    <p>
      Typically, projects use the same license for their API reference as for 
      the project’s code itself, to avoid confusion. Some other projects use
      CC-BY-SA 3.0 for all their reference documentation. The choice is yours.
    </p>

    <p>
      As shown in the <link xref="#standard-layout">Standard Layout</link> you
      should include a <file>license.xml</file> in the top-level gtk-doc DocBook
      file which gives the full text of your documentation license.
    </p>
  </section>

  <section id="public-api">
    <title>Δημόσια API</title>

    <p>
      All public APIs must have gtk-doc comments. For functions, these should
      be placed in the source file, directly above the function.
    </p>

    <code mime="text/x-csrc" style="valid">/**
 * gtk_get_flow:
 * @widget: a #GtkWidget
 *
 * Gets the flow of a widget.
 *
 * Note that flows may be laminar or turbulent...
 *
 * Returns: (transfer none): the flow of @widget
 */
GtkFlow *
gtk_get_flow (GtkWidget *widget)
{

  ...

}</code>

    <p>
      Documentation comments for macros, function types, class
      structs, etc. should be placed next to the definitions, typically
      in header files.
    </p>

    <p>
      Section introductions should be placed in the source file they describe,
      after the license header:
    </p>

    <code mime="text/x-csrc" style="valid">/**
 * SECTION:gtksizerequest
 * @Short_Description: Height-for-width geometry management
 * @Title: GtkSizeRequest
 *
 * The GtkSizeRequest interface is GTK+'s height-for-width (and
 * width-for-height) geometry management system.
 * ...
 */</code>

    <p>
      Keep in mind that in order to include a function, macro,
      function type, or struct type, it needs to be listed in your
      documentation’s <file>modulename-sections.txt</file> file.
    </p>

    <p>
      To properly document a new class, it needs to be given its own
      section in <file>modulename-sections.txt</file>, needs to be
      included in your toplevel <file>modulename-docs.sgml</file>,
      and the <code>get_type()</code> function for your class needs
      to be listed in your <file>modulename.types</file>.
    </p>
  </section>

  <section id="introspection-annotations">
    <title>Introspection Annotations</title>

    <p>
      Each gtk-doc comment should have appropriate
      <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations">
      GObject introspection annotations</link>. These are useful for two
      reasons:
    </p>
    <list type="numbered">
      <item><p>
        They add important information about parameter types, nullability and
        memory management to the C API documentation generated by gtk-doc.
      </p></item>
      <item><p>
        They allow public APIs to be automatically bound in other languages,
        such as Python or JavaScript.
      </p></item>
    </list>

    <p>
      Introspection annotations add information to APIs (functions, function
      parameters, function return values, structures, GObject properties,
      GObject signals) which is otherwise not present in the machine readable C
      API and only exists in the form of human readable documentation or
      convention. They are very important.
    </p>

    <p>
      In gtk-doc comments, annotations should be preferred over human-readable
      equivalents. For example, when documenting a function parameter which may
      be <code>NULL</code>, use the <code>(nullable)</code> annotation rather
      than some text:
    </p>
    <code mime="text/x-csrc" style="valid">/**
 * my_function:
 * @parameter: (nullable): some parameter which affects something
 *
 * Body of the function documentation.
 */</code>

    <p>Αντί για:</p>
    <code mime="text/x-csrc" style="invalid">/**
 * my_bad_function:
 * @parameter: some parameter which affects something, or %NULL to ignore
 *
 * Bad body of the function documentation.
 */</code>

    <p>
      For more information on introspection, see the
      <link xref="introspection">introspection guidelines</link>.
    </p>
  </section>

  <section id="symbol-versioning">
    <title>Symbol Versioning</title>

    <p>
      Whenever a symbol is added to the public API, it should have a
      documentation comment added. This comment should always contain a
      <code>Since</code> line with the package version number of the release
      which will first contain the new API. This should be the number currently
      in <file>configure.ac</file> if
      <link xref="versioning#release-process">post-release version
      incrementing</link> is being used.
    </p>

    <p>Για παράδειγμα:</p>
    <code mime="text/x-csrc" style="valid">/**
 * my_function:
 * @param: some parameter
 *
 * Body of the function documentation.
 *
 * Since: 0.5.0
 */</code>

    <p>
      gtk-doc uses this information to generate indexes of the APIs added in
      each release. These should be added to the main <file>*-docs.xml</file> as
      an appendix:
    </p>
    <code mime="application/docbook+xml">&lt;part&gt;
	&lt;title&gt;Appendices&lt;/title&gt;
	&lt;index id="api-index-full"&gt;
		&lt;title&gt;API Index&lt;/title&gt;
		&lt;xi:include href="xml/api-index-full.xml"&gt;&lt;xi:fallback/&gt;&lt;/xi:include&gt;
	&lt;/index&gt;
	&lt;index id="api-index-deprecated"&gt;
		&lt;title&gt;Index of deprecated symbols&lt;/title&gt;
		&lt;xi:include href="xml/api-index-deprecated.xml"&gt;&lt;xi:fallback/&gt;&lt;/xi:include&gt;
	&lt;/index&gt;
	&lt;index role="0.1.0"&gt;
		&lt;title&gt;Index of new symbols in 0.1.0&lt;/title&gt;
		&lt;xi:include href="xml/api-index-0.1.0.xml"&gt;&lt;xi:fallback/&gt;&lt;/xi:include&gt;
	&lt;/index&gt;
	&lt;!-- More versions here. --&gt;
	&lt;xi:include href="xml/annotation-glossary.xml"&gt;&lt;xi:fallback /&gt;&lt;/xi:include&gt;
&lt;/part&gt;</code>
  </section>

  <section id="dbus-api">
    <title>D-Bus API</title>

    <p>
      D-Bus interface descriptions contain documentation comments, and these can
      be extracted from the XML using <cmd>gdbus-codegen</cmd>, and turned into
      DocBook files to be included by gtk-doc.
    </p>

    <p>
      The DocBook files can be included in the main <file>*-docs.xml</file> file
      using:
    </p>
    <code mime="application/docbook+xml">&lt;chapter&gt;
  &lt;title&gt;C Interfaces&lt;/title&gt;
  &lt;partintro&gt;
    &lt;para&gt;C wrappers for the D-Bus interfaces.&lt;/para&gt;
  &lt;/partintro&gt;

  &lt;xi:include href="xml/SomeDBusService.xml"/&gt;
  &lt;xi:include href="xml/SomeOtherService.xml"/&gt;
&lt;/chapter&gt;</code>

    <p>
      The generated XML files must be included in the <code>content_files</code>
      variable in your gtk-doc <file>Makefile.am</file>, otherwise the build
      will fail. (This is to fix situations where the <code>builddir</code> does
      not equal the <code>srcdir</code>.)
    </p>
  </section>

  <section id="keeping-up-to-date">
    <title>Keeping Documentation Up to Date</title>

    <p>
      gtk-doc comes with support for checking the documentation with some basic
      tests. These check that all version indexes are included in the main
      <file>*-docs.xml</file> file and that all symbols are documented, among
      other things.
    </p>

    <p>
      These tests should always be enabled, by adding the following to your
      gtk-doc <file>Makefile.am</file>:
    </p>
    <code>TESTS = $(GTKDOC_CHECK)</code>

    <p>
      They will then be run as part of <cmd>make check</cmd>.
    </p>
  </section>
</page>