[latexila/wip/build-tools-revamp] Doc fixes

[Sébastien Wilmet <swilmet src gnome org>]

commit 12467c71b20e1ae30bf436d35546c520d0987368
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Wed Apr 30 19:57:22 2014 +0200

    Doc fixes

 docs/reference/Makefile.am                      |    6 ++-
 docs/reference/latexila-sections.txt            |   14 +++++-
 src/liblatexila/latexila-build-tools-personal.c |   29 ++++++------
 src/liblatexila/latexila-build-tools.c          |   17 +++++---
 src/liblatexila/latexila-build-tools.h          |   54 +++++++++++++++++------
 5 files changed, 81 insertions(+), 39 deletions(-)
---
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 9f2fa03..d059ab3 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -52,7 +52,9 @@ EXTRA_HFILES =
 
 # Header files or dirs to ignore when scanning. Use base file/dir names
 # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code
-IGNORE_HFILES =
+IGNORE_HFILES =                                        \
+       latexila-post-processor.h               \
+       latexila-post-processor-all-output.h
 
 # Images to copy into HTML directory.
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
@@ -80,7 +82,7 @@ include $(top_srcdir)/gtk-doc.make
 
 # Other files to distribute
 # e.g. EXTRA_DIST += version.xml.in
-EXTRA_DIST =
+EXTRA_DIST +=
 
 # Files not to distribute
 # for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
diff --git a/docs/reference/latexila-sections.txt b/docs/reference/latexila-sections.txt
index e79140f..544000c 100644
--- a/docs/reference/latexila-sections.txt
+++ b/docs/reference/latexila-sections.txt
@@ -3,9 +3,14 @@
 <SECTION>
 <FILE>build-tools</FILE>
 <TITLE>LatexilaBuildTools</TITLE>
-LatexilaBuildToolsPrivate
+LatexilaBuildTools
+LatexilaBuildTool
+LatexilaBuildJob
+LatexilaPostProcessorType
 latexila_build_tool_get_description
 latexila_build_tool_free
+latexila_get_post_processor_type_from_name
+latexila_get_post_processor_name_from_type
 latexila_build_tools_load
 latexila_build_tools_set_enabled
 <SUBSECTION Standard>
@@ -16,12 +21,13 @@ LATEXILA_IS_BUILD_TOOLS
 LATEXILA_IS_BUILD_TOOLS_CLASS
 LATEXILA_TYPE_BUILD_TOOLS
 latexila_build_tools_get_type
+LatexilaBuildToolsPrivate
 </SECTION>
 
 <SECTION>
 <FILE>build-tools-default</FILE>
 <TITLE>LatexilaBuildToolsDefault</TITLE>
-LatexilaBuildToolsDefaultPrivate
+LatexilaBuildToolsDefault
 latexila_build_tools_default_get_instance
 <SUBSECTION Standard>
 LATEXILA_BUILD_TOOLS_DEFAULT
@@ -31,12 +37,13 @@ LATEXILA_IS_BUILD_TOOLS_DEFAULT
 LATEXILA_IS_BUILD_TOOLS_DEFAULT_CLASS
 LATEXILA_TYPE_BUILD_TOOLS_DEFAULT
 latexila_build_tools_default_get_type
+LatexilaBuildToolsDefaultPrivate
 </SECTION>
 
 <SECTION>
 <FILE>build-tools-personal</FILE>
 <TITLE>LatexilaBuildToolsPersonal</TITLE>
-LatexilaBuildToolsPersonalPrivate
+LatexilaBuildToolsPersonal
 latexila_build_tools_personal_get_instance
 latexila_build_tools_personal_save
 latexila_build_tools_personal_move_up
@@ -53,4 +60,5 @@ LATEXILA_IS_BUILD_TOOLS_PERSONAL
 LATEXILA_IS_BUILD_TOOLS_PERSONAL_CLASS
 LATEXILA_TYPE_BUILD_TOOLS_PERSONAL
 latexila_build_tools_personal_get_type
+LatexilaBuildToolsPersonalPrivate
 </SECTION>
diff --git a/src/liblatexila/latexila-build-tools-personal.c b/src/liblatexila/latexila-build-tools-personal.c
index ddd6567..1325600 100644
--- a/src/liblatexila/latexila-build-tools-personal.c
+++ b/src/liblatexila/latexila-build-tools-personal.c
@@ -150,7 +150,7 @@ save_cb (GFile                      *xml_file,
 
 /**
  * latexila_build_tools_personal_save:
- * @build_tools: a #LatexilaBuildToolsPersonal object.
+ * @build_tools: the #LatexilaBuildToolsPersonal instance.
  *
  * Saves the personal build tools into the XML file.
  */
@@ -243,8 +243,8 @@ latexila_build_tools_personal_save (LatexilaBuildToolsPersonal *build_tools)
 
 /**
  * latexila_build_tools_personal_move_up:
- * @build_tools:
- * @tool_num:
+ * @build_tools: the #LatexilaBuildToolsPersonal instance.
+ * @tool_num: the build tool position in the list.
  *
  * Move a build tool up. The first build tool is at the top.
  */
@@ -277,8 +277,8 @@ latexila_build_tools_personal_move_up (LatexilaBuildToolsPersonal *build_tools,
 
 /**
  * latexila_build_tools_personal_move_down:
- * @build_tools:
- * @tool_num:
+ * @build_tools: the #LatexilaBuildToolsPersonal instance.
+ * @tool_num: the build tool position in the list.
  *
  * Move a build tool down. The first build tool is at the top.
  */
@@ -335,10 +335,10 @@ latexila_build_tools_personal_delete (LatexilaBuildToolsPersonal *build_tools,
 
 /**
  * latexila_build_tools_personal_add:
- * @build_tools:
- * @new_build_tool:
+ * @build_tools: the #LatexilaBuildToolsPersonal instance.
+ * @new_build_tool: the new build tool structure.
  *
- * Append the new build tool at the end.
+ * Append the new build tool at the end of the list.
  */
 void
 latexila_build_tools_personal_add (LatexilaBuildToolsPersonal *build_tools,
@@ -356,9 +356,9 @@ latexila_build_tools_personal_add (LatexilaBuildToolsPersonal *build_tools,
 
 /**
  * latexila_build_tools_personal_insert:
- * @build_tools:
- * @new_build_tool:
- * @position:
+ * @build_tools: the #LatexilaBuildToolsPersonal instance.
+ * @new_build_tool: the new build tool structure.
+ * @position: the position in the list where to insert the new build tool.
  *
  * Inserts a new build tool at a given position.
  */
@@ -380,9 +380,10 @@ latexila_build_tools_personal_insert (LatexilaBuildToolsPersonal *build_tools,
 
 /**
  * latexila_build_tools_personal_replace:
- * @build_tools:
- * @new_build_tool:
- * @position:
+ * @build_tools: the #LatexilaBuildToolsPersonal instance.
+ * @new_build_tool: the new build tool structure.
+ * @position: the position in the list where to replace the build tool. The old
+ * build tool structure located at @position will be freed.
  *
  * Replaces a build tool.
  */
diff --git a/src/liblatexila/latexila-build-tools.c b/src/liblatexila/latexila-build-tools.c
index 06a9336..04e634a 100644
--- a/src/liblatexila/latexila-build-tools.c
+++ b/src/liblatexila/latexila-build-tools.c
@@ -23,7 +23,12 @@
  * @short_description: Build tools base class
  *
  * Base class for the build tools. The build tools are stored in an XML file.
- * The XML file is loaded into data structures in memory.
+ * The XML file contents is loaded into data structures in memory.
+ * There are two subclasses: #LatexilaBuildToolsDefault and
+ * #LatexilaBuildToolsPersonal. The default build tools and personal build tools
+ * have a different behavior. A personal build tool can be modified for example,
+ * while a default build tool can only be enabled or disabled. That's why
+ * subclasses exist.
  */
 
 #include "config.h"
@@ -524,8 +529,8 @@ load_contents_cb (GFile              *xml_file,
 
 /**
  * latexila_build_tools_load:
- * @build_tools:
- * @xml_file:
+ * @build_tools: a #LatexilaBuildTools object.
+ * @xml_file: the XML file.
  *
  * Loads asynchronously the XML file contents and parses it.
  * This function is used by subclasses of #LatexilaBuildTools.
@@ -550,9 +555,9 @@ latexila_build_tools_load (LatexilaBuildTools *build_tools,
 
 /**
  * latexila_build_tools_set_enabled:
- * @build_tools:
- * @tool_num:
- * @enabled:
+ * @build_tools: a #LatexilaBuildTools object.
+ * @tool_num: the build tool position in the list.
+ * @enabled: whether to enable the build tool.
  */
 void
 latexila_build_tools_set_enabled (LatexilaBuildTools *build_tools,
diff --git a/src/liblatexila/latexila-build-tools.h b/src/liblatexila/latexila-build-tools.h
index 1677694..e097e20 100644
--- a/src/liblatexila/latexila-build-tools.h
+++ b/src/liblatexila/latexila-build-tools.h
@@ -34,16 +34,23 @@ G_BEGIN_DECLS
 
 typedef struct _LatexilaBuildToolsClass   LatexilaBuildToolsClass;
 typedef struct _LatexilaBuildToolsPrivate LatexilaBuildToolsPrivate;
+typedef struct _LatexilaBuildJob          LatexilaBuildJob;
+typedef struct _LatexilaBuildTool         LatexilaBuildTool;
 
+/**
+ * LatexilaBuildTools:
+ * @build_tools: a list of #LatexilaBuildTool's. External code should just read
+ * the list, not modify it.
+ */
 struct _LatexilaBuildTools
 {
+  /*< private >*/
   GObject parent;
 
-  /* A list of LatexilaBuildTool's.
-   * External code should just read the list, not modify it.
-   */
+  /*< public >*/
   GList *build_tools;
 
+  /*< private >*/
   LatexilaBuildToolsPrivate *priv;
 };
 
@@ -52,6 +59,15 @@ struct _LatexilaBuildToolsClass
   GObjectClass parent_class;
 };
 
+/**
+ * LatexilaPostProcessorType:
+ * @LATEXILA_POST_PROCESSOR_TYPE_NO_OUTPUT: no output.
+ * @LATEXILA_POST_PROCESSOR_TYPE_ALL_OUTPUT: all output.
+ * @LATEXILA_POST_PROCESSOR_TYPE_LATEX: for a LaTeX command.
+ * @LATEXILA_POST_PROCESSOR_TYPE_LATEXMK: for the latexmk command.
+ *
+ * Types of post-processors.
+ */
 typedef enum
 {
   LATEXILA_POST_PROCESSOR_TYPE_NO_OUTPUT,
@@ -60,30 +76,40 @@ typedef enum
   LATEXILA_POST_PROCESSOR_TYPE_LATEXMK
 } LatexilaPostProcessorType;
 
-typedef struct
+/**
+ * LatexilaBuildJob:
+ * @post_processor_type: the post-processor type.
+ * @command: the command to run.
+ */
+struct _LatexilaBuildJob
 {
   LatexilaPostProcessorType post_processor_type;
   gchar *command;
-} LatexilaBuildJob;
+};
 
-typedef struct
+/**
+ * LatexilaBuildTool:
+ * @label: the label.
+ * @description: the description.
+ * @extensions: the extensions.
+ * @icon: the icon.
+ * @files_to_open: the files to open.
+ * @jobs: a list of #LatexilaBuildJob's.
+ * @id: ID of the build tool. It is used only by the default build tools, for
+ * saving in #GSettings the lists of enabled/disabled build tools.
+ * @enabled: whether the build tool is enabled (for showing it in the UI).
+ */
+struct _LatexilaBuildTool
 {
   gchar *label;
   gchar *description;
   gchar *extensions;
   gchar *icon;
   gchar *files_to_open;
-
-  /* A list of LatexilaBuildJob's */
   GSList *jobs;
-
-  /* The id is used only by the default build tools.
-   * It is used to save those are enabled or disabled.
-   */
   gint id;
-
   guint enabled : 1;
-} LatexilaBuildTool;
+};
 
 GType                 latexila_build_tools_get_type                 (void) G_GNUC_CONST;