[geary/wip/728002-webkit2: 49/105] Valadoc generation fixes & updates.

[Michael Gratton <mjog src gnome org>]

commit 4d00b1b64630b9f999fe5f45a8c3a20b48a0880a
Author: Michael James Gratton <mike vee net>
Date:   Fri Dec 30 18:36:42 2016 +1100

    Valadoc generation fixes & updates.
    
    * configure: Allow specifying a custom valadoc executable.
    
    * src/CMakeLists.txt: Tidy up valadoc command, include dependencies when
      in generated HTML output, enable warnings.
    
    * src/engine/api/geary.vala: Provide boilerplate doc comment for the
      Geary namespace.
    
    * src/engine/api/geary-email.vala, src/engine/rfc822/rfc822.vala: Don't
      use single-line doc comments, valadoc doesn't support them (see Bug
      736483).
    
    * src/engine/api/geary-folder-path.vala: Fix errors reported by valadoc.

 configure                             |   15 +++++++++++++++
 src/CMakeLists.txt                    |   24 ++++++++++++++++--------
 src/engine/api/geary-email.vala       |    4 +++-
 src/engine/api/geary-engine.vala      |    1 -
 src/engine/api/geary-folder-path.vala |    4 ++--
 src/engine/api/geary.vala             |   17 +++++++++++++++++
 src/engine/rfc822/rfc822.vala         |    4 +++-
 7 files changed, 56 insertions(+), 13 deletions(-)
---
diff --git a/configure b/configure
index 0d2b5ee..b802baf 100755
--- a/configure
+++ b/configure
@@ -148,6 +148,21 @@ then
     CMDLINE="${CMDLINE} -DVALA_EXECUTABLE='$VALA_EXECUTABLE'"
 fi
 
+# Verify use supplied valadoc executable
+if [ -n "$VALADOC" ]
+then
+    VALADOC_EXECUTABLE=`type -p "$VALADOC"`
+
+    if [ -z "$VALADOC_EXECUTABLE" ]
+    then
+        printf "$VALADOC is not an executable program.\n"
+        exit 1
+    fi
+
+    CMDLINE="${CMDLINE} -DVALADOC_EXECUTABLE='$VALADOC_EXECUTABLE'"
+fi
+
+
 # Verify cmake is installed
 # TODO: Check for minimum version number
 if ! cmake --version
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index 5ae8fa1..ec1a49b 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -3,6 +3,7 @@
 
 set(ENGINE_SRC
 
+engine/api/geary.vala
 engine/api/geary-abstract-local-folder.vala
 engine/api/geary-account.vala
 engine/api/geary-account-information.vala
@@ -595,8 +596,8 @@ set(VALAC_OPTIONS
     --metadatadir=${CMAKE_SOURCE_DIR}/bindings/metadata/${WEBKITGTK_METADATA_DIR}
     --target-glib=${TARGET_GLIB}
     --thread
-    --enable-checking
     --debug
+    --enable-checking
     --enable-deprecated
     --fatal-warnings
     ${EXTRA_VALA_OPTIONS}
@@ -729,17 +730,24 @@ add_custom_command(
 # Valadoc
 #################################################
 foreach(pkg ${ENGINE_PACKAGES})
-    list(APPEND valadoc_pkg_opts "--pkg=${pkg}")
+    list(APPEND VALADOC_PKG_OPTS "--pkg=${pkg}")
 endforeach(pkg ${ENGINE_PACKAGES})
 
 include(FindValadoc)
-add_custom_target(
-    valadoc
-    WORKING_DIRECTORY
-        ${CMAKE_SOURCE_DIR}/src
-    COMMAND
-        ${VALADOC_EXECUTABLE} --force --no-protected --target-glib=${TARGET_GLIB} -b 
${CMAKE_CURRENT_SOURCE_DIR} -o ${CMAKE_SOURCE_DIR}/valadoc --package-name=geary --package-version=${VERSION} 
${ENGINE_SRC} ${valadoc_pkg_opts} --vapidir=${CMAKE_SOURCE_DIR}/bindings/vapi
+add_custom_target(valadoc
+  WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/src
+  COMMAND ${VALADOC_EXECUTABLE}
+    --verbose --force --deps
+    --package-name=geary-${VERSION}
+    --package-version=${VERSION}
+    --target-glib=${TARGET_GLIB}
+    -b ${CMAKE_CURRENT_SOURCE_DIR}
+    -o ${CMAKE_SOURCE_DIR}/valadoc
+    --vapidir=${CMAKE_BINARY_DIR}/src
+    --vapidir=${CMAKE_SOURCE_DIR}/bindings/vapi
+    ${VALADOC_PKG_OPTS} ${ENGINE_SRC}
 )
+add_dependencies(valadoc git-version)
 
 ## Make clean: remove copied files
 ##################################################
diff --git a/src/engine/api/geary-email.vala b/src/engine/api/geary-email.vala
index 2d26c08..16d01da 100644
--- a/src/engine/api/geary-email.vala
+++ b/src/engine/api/geary-email.vala
@@ -12,7 +12,9 @@
  */
 public class Geary.Email : BaseObject {
 
-    /** The maximum expected length of message body preview text. */
+    /**
+     * The maximum expected length of message body preview text.
+     */
     public const int MAX_PREVIEW_BYTES = 256;
 
     /**
diff --git a/src/engine/api/geary-engine.vala b/src/engine/api/geary-engine.vala
index 3294af5..e532732 100644
--- a/src/engine/api/geary-engine.vala
+++ b/src/engine/api/geary-engine.vala
@@ -14,7 +14,6 @@
  * Engine can list existing {@link Account} objects and create/delete them.  It can also validate
  * changes to Accounts prior to saving those changes.
  */
-
 public class Geary.Engine : BaseObject {
 
     private const string ID_PREFIX = "account_";
diff --git a/src/engine/api/geary-folder-path.vala b/src/engine/api/geary-folder-path.vala
index 59a4afa..9752f21 100644
--- a/src/engine/api/geary-folder-path.vala
+++ b/src/engine/api/geary-folder-path.vala
@@ -251,7 +251,7 @@ public class Geary.FolderPath : BaseObject, Gee.Hashable<Geary.FolderPath>,
      * are less-than longer paths, assuming the path elements are equal up to the shorter path's
      * length.
      *
-     * Note that {@link FolderRoot.case_sensitive} affects comparisons.
+     * Note that {@link FolderPath.case_sensitive} affects comparisons.
      *
      * Returns -1 if this path is lexiographically before the other, 1 if its after, and 0 if they
      * are equal.
@@ -263,7 +263,7 @@ public class Geary.FolderPath : BaseObject, Gee.Hashable<Geary.FolderPath>,
     /**
      * {@inheritDoc}
      *
-     * Note that {@link FolderRoot.case_sensitive} affects comparisons.
+     * Note that {@link FolderPath.case_sensitive} affects comparisons.
      */
     public uint hash() {
         if (stored_hash != uint.MAX)
diff --git a/src/engine/api/geary.vala b/src/engine/api/geary.vala
new file mode 100644
index 0000000..de5ea8f
--- /dev/null
+++ b/src/engine/api/geary.vala
@@ -0,0 +1,17 @@
+/* Copyright 2016 Michael Gratton <mike vee net>
+ *
+ * This software is licensed under the GNU Lesser General Public License
+ * (version 2.1 or later). See the COPYING file in this distribution.
+ */
+
+/**
+ * The primary namespace for the Geary email library.
+ *
+ * For the main entry point, see {@link Geary.Engine}.
+ */
+namespace Geary {
+
+    // This source file exists purely as a place for the namespace's
+    // documentation comment.
+
+}
diff --git a/src/engine/rfc822/rfc822.vala b/src/engine/rfc822/rfc822.vala
index 486acec..49b9e05 100644
--- a/src/engine/rfc822/rfc822.vala
+++ b/src/engine/rfc822/rfc822.vala
@@ -14,7 +14,9 @@ public enum TextFormat {
     HTML
 }
 
-/** Offical IANA charset encoding name for UTF-8. */
+/**
+ * Official IANA charset encoding name for UTF-8.
+ */
 public const string UTF8_CHARSET = "UTF-8";
 
 // This has the effect of ensuring all non US-ASCII and non-ISO-8859-1