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

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

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

    Doc fixes

 docs/reference/latexila-sections.txt            |    4 ++
 src/liblatexila/latexila-build-tools-personal.c |   29 ++++++++-------
 src/liblatexila/latexila-build-tools.c          |   10 +++---
 src/liblatexila/latexila-build-tools.h          |   43 +++++++++++++++++------
 4 files changed, 56 insertions(+), 30 deletions(-)
---
diff --git a/docs/reference/latexila-sections.txt b/docs/reference/latexila-sections.txt
index e79140f..f4c89e2 100644
--- a/docs/reference/latexila-sections.txt
+++ b/docs/reference/latexila-sections.txt
@@ -3,7 +3,11 @@
 <SECTION>
 <FILE>build-tools</FILE>
 <TITLE>LatexilaBuildTools</TITLE>
+LatexilaBuildTools
 LatexilaBuildToolsPrivate
+LatexilaBuildTool
+LatexilaBuildJob
+LatexilaPostProcessorType
 latexila_build_tool_get_description
 latexila_build_tool_free
 latexila_build_tools_load
diff --git a/src/liblatexila/latexila-build-tools-personal.c b/src/liblatexila/latexila-build-tools-personal.c
index ddd6567..1db7fb2 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 #LatexilaBuildToolPersonal 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..e030c79 100644
--- a/src/liblatexila/latexila-build-tools.c
+++ b/src/liblatexila/latexila-build-tools.c
@@ -524,8 +524,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 +550,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..8294955 100644
--- a/src/liblatexila/latexila-build-tools.h
+++ b/src/liblatexila/latexila-build-tools.h
@@ -34,6 +34,8 @@ G_BEGIN_DECLS
 
 typedef struct _LatexilaBuildToolsClass   LatexilaBuildToolsClass;
 typedef struct _LatexilaBuildToolsPrivate LatexilaBuildToolsPrivate;
+typedef struct _LatexilaBuildJob          LatexilaBuildJob;
+typedef struct _LatexilaBuildTool         LatexilaBuildTool;
 
 struct _LatexilaBuildTools
 {
@@ -52,6 +54,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 +71,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;