[geary] Fix valadoc warnings, generate internal docs rather than docs for deps.

From: Michael Gratton <mjog src gnome org>
To: commits-list gnome org
Cc:
Subject: [geary] Fix valadoc warnings, generate internal docs rather than docs for deps.
Date: Tue, 9 Jan 2018 07:29:24 +0000 (UTC)
commit acba774839089a95c1db4b7ddcb04fc087f880dc
Author: Michael James Gratton <mike vee net>
Date:   Tue Jan 9 18:28:29 2018 +1100

    Fix valadoc warnings, generate internal docs rather than docs for deps.
    
    This lets valadoc build Geary's engine docs again as long as patches for
    valadoc Bug 736483 and Bug 646982 are applied (which will hopefully be
    merged for vala 0.40). Once Bug 792349 is also fixed, we'll be able to
    generate private docs as well.

 src/CMakeLists.txt                                 |    2 +-
 src/engine/api/geary-account.vala                  |   28 ++++----
 src/engine/api/geary-attachment.vala               |   10 ++--
 src/engine/api/geary-folder-path.vala              |    3 +-
 src/engine/api/geary-folder.vala                   |    5 +-
 src/engine/app/app-conversation.vala               |    2 +-
 src/engine/db/db.vala                              |   20 ++++--
 src/engine/imap-db/imap-db-gc.vala                 |   17 +++--
 src/engine/imap-db/outbox/smtp-outbox-folder.vala  |    2 +-
 .../imap-db/search/imap-db-search-query.vala       |   35 ++++++----
 .../imap-engine/imap-engine-generic-account.vala   |   27 +++++---
 .../imap-engine/imap-engine-replay-operation.vala  |   68 ++++++++++++--------
 .../replay-ops/imap-engine-move-email-prepare.vala |   11 ++-
 src/engine/imap/api/imap-account.vala              |    4 +-
 src/engine/imap/api/imap-folder.vala               |    7 +-
 .../imap/command/imap-namespace-command.vala       |    2 +-
 .../imap/message/imap-mailbox-specifier.vala       |   15 +++--
 src/engine/rfc822/rfc822-message.vala              |    2 +-
 src/engine/util/util-idle-manager.vala             |    2 +-
 src/meson.build                                    |    5 +-
 20 files changed, 156 insertions(+), 111 deletions(-)
---
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index 681dd57..20edd74 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -802,7 +802,7 @@ include(FindValadoc)
 add_custom_target(valadoc
   WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/src
   COMMAND ${VALADOC_EXECUTABLE}
-    --verbose --force --deps
+    --verbose --force --internal
     --package-name=geary-${VERSION}
     --package-version=${VERSION}
     --target-glib=${TARGET_GLIB}
diff --git a/src/engine/api/geary-account.vala b/src/engine/api/geary-account.vala
index a7fd343..685b30c 100644
--- a/src/engine/api/geary-account.vala
+++ b/src/engine/api/geary-account.vala
@@ -353,61 +353,61 @@ public abstract class Geary.Account : BaseObject {
         return name;
     }
 
-    /** Fires a {@link opened}} signal. */
+    /** Fires a {@link opened} signal. */
     protected virtual void notify_opened() {
         opened();
     }
 
-    /** Fires a {@link closed}} signal. */
+    /** Fires a {@link closed} signal. */
     protected virtual void notify_closed() {
         closed();
     }
 
-    /** Fires a {@link folders_available_unavailable}} signal. */
+    /** Fires a {@link folders_available_unavailable} signal. */
     protected virtual void notify_folders_available_unavailable(Gee.List<Geary.Folder>? available,
                                                                 Gee.List<Geary.Folder>? unavailable) {
         folders_available_unavailable(available, unavailable);
     }
 
-    /** Fires a {@link folders_added_removed}} signal. */
+    /** Fires a {@link folders_added_removed} signal. */
     protected virtual void notify_folders_added_removed(Gee.List<Geary.Folder>? added,
         Gee.List<Geary.Folder>? removed) {
         folders_added_removed(added, removed);
     }
 
-    /** Fires a {@link folders_contents_altered}} signal. */
+    /** Fires a {@link folders_contents_altered} signal. */
     protected virtual void notify_folders_contents_altered(Gee.Collection<Geary.Folder> altered) {
         folders_contents_altered(altered);
     }
 
-    /** Fires a {@link email_appended}} signal. */
+    /** Fires a {@link email_appended} signal. */
     protected virtual void notify_email_appended(Geary.Folder folder, Gee.Collection<Geary.EmailIdentifier> 
ids) {
         email_appended(folder, ids);
     }
 
-    /** Fires a {@link email_inserted}} signal. */
+    /** Fires a {@link email_inserted} signal. */
     protected virtual void notify_email_inserted(Geary.Folder folder, Gee.Collection<Geary.EmailIdentifier> 
ids) {
         email_inserted(folder, ids);
     }
 
-    /** Fires a {@link email_removed}} signal. */
+    /** Fires a {@link email_removed} signal. */
     protected virtual void notify_email_removed(Geary.Folder folder, Gee.Collection<Geary.EmailIdentifier> 
ids) {
         email_removed(folder, ids);
     }
 
-    /** Fires a {@link email_locally_complete}} signal. */
+    /** Fires a {@link email_locally_complete} signal. */
     protected virtual void notify_email_locally_complete(Geary.Folder folder,
         Gee.Collection<Geary.EmailIdentifier> ids) {
         email_locally_complete(folder, ids);
     }
 
-    /** Fires a {@link email_discovered}} signal. */
+    /** Fires a {@link email_discovered} signal. */
     protected virtual void notify_email_discovered(Geary.Folder folder,
         Gee.Collection<Geary.EmailIdentifier> ids) {
         email_discovered(folder, ids);
     }
 
-    /** Fires a {@link email_flags_changed}} signal. */
+    /** Fires a {@link email_flags_changed} signal. */
     protected virtual void notify_email_flags_changed(Geary.Folder folder,
         Gee.Map<Geary.EmailIdentifier, Geary.EmailFlags> flag_map) {
         email_flags_changed(folder, flag_map);
@@ -417,19 +417,19 @@ public abstract class Geary.Account : BaseObject {
         email_sent(message);
     }
 
-    /** Fires a {@link report_problem}} signal for this account. */
+    /** Fires a {@link report_problem} signal for this account. */
     protected virtual void notify_report_problem(ProblemReport report) {
         report_problem(report);
     }
 
     /**
-     * Fires a {@link report_problem}} signal for this account.
+     * Fires a {@link report_problem} signal for this account.
      */
     protected virtual void notify_account_problem(ProblemType type, Error? err) {
         report_problem(new AccountProblemReport(type, this.information, err));
     }
 
-    /** Fires a {@link report_problem}} signal for a service for this account. */
+    /** Fires a {@link report_problem} signal for a service for this account. */
     protected virtual void notify_service_problem(ProblemType type, Service service_type, Error? err) {
         report_problem(new ServiceProblemReport(type, this.information, service_type, err));
     }
diff --git a/src/engine/api/geary-attachment.vala b/src/engine/api/geary-attachment.vala
index d46b66e..24285e2 100644
--- a/src/engine/api/geary-attachment.vala
+++ b/src/engine/api/geary-attachment.vala
@@ -1,4 +1,5 @@
-/* Copyright 2016 Software Freedom Conservancy Inc.
+/*
+ * Copyright 2016 Software Freedom Conservancy Inc.
  *
  * This software is licensed under the GNU Lesser General Public License
  * (version 2.1 or later).  See the COPYING file in this distribution.
@@ -6,17 +7,14 @@
 
 /**
  * An attachment that was a part of an {@link Email}.
- *
- * @see Email.get_attachment
  */
-
 public abstract class Geary.Attachment : BaseObject {
 
 
     /**
      * An identifier that can be used to locate the {@link Attachment} in an {@link Email}.
      *
-     * @see Email.get_attachment
+     * @see Email.get_attachment_by_id
      */
     public string id { get; private set; }
 
@@ -29,6 +27,8 @@ public abstract class Geary.Attachment : BaseObject {
      * The Content-ID of the attachment.
      *
      * See [[https://tools.ietf.org/html/rfc2111]]
+     *
+     * @see Email.get_attachment_by_content_id
      */
     public string? content_id { get; private set; }
 
diff --git a/src/engine/api/geary-folder-path.vala b/src/engine/api/geary-folder-path.vala
index 7f0bf7b..b118be2 100644
--- a/src/engine/api/geary-folder-path.vala
+++ b/src/engine/api/geary-folder-path.vala
@@ -278,7 +278,8 @@ public class Geary.FolderPath : BaseObject, Gee.Hashable<Geary.FolderPath>,
      * Returns a string version of the path using a default separator.
      *
      * Do not use this for obtaining an IMAP mailbox name to send to a
-     * server, use {@link Geary.Imap.MailboxSpecifier.from_folder_path}
+     * server, use {@link
+     * Geary.Imap.MailboxSpecifier.MailboxSpecifier.from_folder_path}
      * instead. This method is useful for debugging and logging only.
      */
     public string to_string() {
diff --git a/src/engine/api/geary-folder.vala b/src/engine/api/geary-folder.vala
index e33852d..d07a400 100644
--- a/src/engine/api/geary-folder.vala
+++ b/src/engine/api/geary-folder.vala
@@ -1,4 +1,5 @@
-/* Copyright 2016 Software Freedom Conservancy Inc.
+/*
+ * Copyright 2016 Software Freedom Conservancy Inc.
  *
  * This software is licensed under the GNU Lesser General Public License
  * (version 2.1 or later).  See the COPYING file in this distribution.
@@ -25,7 +26,7 @@
  * were appended to the folder, not when messages were sent or some
  * other criteria. For remote-backed folders, the engine will maintain
  * the vector in accordance with the value of {@link
- * AccountInformation.prefetch-period-days}, however the start of the
+ * AccountInformation.prefetch_period_days}, however the start of the
  * vector will be extended back past that over time and in response to
  * certain operations that cause the vector to be ''expanded'' ---
  * that is for additional messages to be loaded from the remote
diff --git a/src/engine/app/app-conversation.vala b/src/engine/app/app-conversation.vala
index 6442710..ffae630 100644
--- a/src/engine/app/app-conversation.vala
+++ b/src/engine/app/app-conversation.vala
@@ -290,7 +290,7 @@ public class Geary.App.Conversation : BaseObject {
      * Add the email to the conversation if not already present.
      *
      * The value of `known_paths` should contain all the known {@link
-     * FolderPaths} this email is contained within.
+     * FolderPath} instances this email is contained within.
      *
      * Returns if the email was added, else false if already present
      * and only `known_paths` were merged.
diff --git a/src/engine/db/db.vala b/src/engine/db/db.vala
index f423166..5b04b1e 100644
--- a/src/engine/db/db.vala
+++ b/src/engine/db/db.vala
@@ -1,19 +1,25 @@
-/* Copyright 2016 Software Freedom Conservancy Inc.
+/*
+ * Copyright 2016 Software Freedom Conservancy Inc.
  *
  * This software is licensed under the GNU Lesser General Public License
  * (version 2.1 or later).  See the COPYING file in this distribution.
  */
 
 /**
- * Geary.Db is a simple wrapper around SQLite to make it more GObject-ish and easier to code in
- * Vala.  It also uses threads and some concurrency features of SQLite to allow for asynchronous
+ * A simple database access layer.
+ *
+ * Geary.Db is a simple wrapper around SQLite to make it more
+ * GObject-ish and easier to code in Vala.  It also uses threads and
+ * some concurrency features of SQLite to allow for asynchronous
  * access to the database.
  *
- * There is no attempt here to hide or genericize the backing database library; this is designed with
- * SQLite in mind.  As such, many of the calls are merely direct front-ends to the underlying
- * SQLite call.
+ * There is no attempt here to hide or genericize the backing database
+ * library; this is designed with SQLite in mind.  As such, many of
+ * the calls are merely direct front-ends to the underlying SQLite
+ * call.
  *
- * The design of the classes and interfaces owes a debt to SQLHeavy (http://code.google.com/p/sqlheavy/).
+ * The design of the classes and interfaces owes a debt to
+ * [[http://code.google.com/p/sqlheavy/|SQLHeavy]].
  */
 
 extern int sqlite3_enable_shared_cache(int enabled);
diff --git a/src/engine/imap-db/imap-db-gc.vala b/src/engine/imap-db/imap-db-gc.vala
index 0ba6227..8d07327 100644
--- a/src/engine/imap-db/imap-db-gc.vala
+++ b/src/engine/imap-db/imap-db-gc.vala
@@ -1,4 +1,5 @@
-/* Copyright 2016 Software Freedom Conservancy Inc.
+/*
+ * Copyright 2016 Software Freedom Conservancy Inc.
  *
  * This software is licensed under the GNU Lesser General Public License
  * (version 2.1 or later).  See the COPYING file in this distribution.
@@ -69,19 +70,17 @@ private class Geary.ImapDB.GC {
          */
         REAP,
         /**
-         * Indicates the caller should run {@link vauum_async} to consolidate disk space and reduce
+         * Indicates the caller should run {@link vacuum_async} to consolidate disk space and reduce
          * database fragmentation.
          */
         VACUUM
     }
-    
+
     /**
      * Indicates the garbage collector is running.
-     *
-     * {@link run_async} will return immediately if called while running.
      */
     public bool is_running { get; private set; default = false; }
-    
+
     private ImapDB.Database db;
     private int priority;
     private File data_dir;
@@ -91,9 +90,11 @@ private class Geary.ImapDB.GC {
         this.priority = priority;
         data_dir = db.db_file.get_parent();
     }
-    
+
     /**
-     * Returns if the GC should be executed (via {@link run_async}).
+     * Determines if the GC should be executed.
+     *
+     * @return a recommendation for the operation client to execute.
      */
     public async RecommendedOperation should_run_async(Cancellable? cancellable) throws Error {
         DateTime? last_reap_time, last_vacuum_time;
diff --git a/src/engine/imap-db/outbox/smtp-outbox-folder.vala 
b/src/engine/imap-db/outbox/smtp-outbox-folder.vala
index 4211392..97f8ebb 100644
--- a/src/engine/imap-db/outbox/smtp-outbox-folder.vala
+++ b/src/engine/imap-db/outbox/smtp-outbox-folder.vala
@@ -183,7 +183,7 @@ private class Geary.SmtpOutboxFolder :
     /**
      * Queues a message in the outbox for delivery.
      *
-     * This should be used instead of {@link create_email_async()},
+     * This should be used instead of {@link create_email_async},
      * since that requires the Outbox be open according to contract,
      * but enqueuing emails for background delivery can happen at any
      * time, so this is the mechanism to do so.
diff --git a/src/engine/imap-db/search/imap-db-search-query.vala 
b/src/engine/imap-db/search/imap-db-search-query.vala
index 9801576..0218500 100644
--- a/src/engine/imap-db/search/imap-db-search-query.vala
+++ b/src/engine/imap-db/search/imap-db-search-query.vala
@@ -1,4 +1,5 @@
 /* Copyright 2016 Software Freedom Conservancy Inc.
+ * Copyright 2016 Software Freedom Conservancy Inc.
  *
  * This software is licensed under the GNU Lesser General Public License
  * (version 2.1 or later).  See the COPYING file in this distribution.
@@ -7,42 +8,49 @@
 /**
  * Internal implementation of {@link Geary.SearchQuery}.
  */
-
 private class Geary.ImapDB.SearchQuery : Geary.SearchQuery {
+
     /**
      * Associated {@link ImapDB.Account}.
      */
     public weak ImapDB.Account account { get; private set; }
-    
+
     /**
-     * Whether or not the query has been parsed and processed prior to search submission.
+     * Whether or not the query has been parsed and processed prior to
+     * search submission.
      */
     public bool parsed { get; set; default = false; }
-    
+
     /**
-     * Determined by {@link strategy}.
+     * Returns whether stemming may be used when exerting the search.
+     *
+     * Determined by {@link Geary.SearchQuery.Strategy} passed to the
+     * constructor.
      */
     public bool allow_stemming { get; private set; }
-    
+
     /**
      * Minimum length of the term before stemming is allowed.
      *
      * This prevents short words that might be stemmed from being stemmed.
      *
-     * Overridden by {@link allow_stemming}.  Determined by {@link strategy}.
+     * Overridden by {@link allow_stemming}. Determined by the {@link
+     * Geary.SearchQuery.Strategy} passed to the constructor.
      */
     public int min_term_length_for_stemming { get; private set; }
-    
+
+
     /**
      * Maximum difference in lengths between term and stemmed variant.
      *
-     * This prevents long words from being stemmed to much shorter words (which creates
-     * opportunities for greedy matching).
+     * This prevents long words from being stemmed to much shorter
+     * words (which creates opportunities for greedy matching).
      *
-     * Overridden by {@link allow_stemming}.  Determined by {@link strategy}.
+     * Overridden by {@link allow_stemming}. Determined by the {@link
+     * Geary.SearchQuery.Strategy} passed to the constructor.
      */
     public int max_difference_term_stem_lengths { get; private set; }
-    
+
     /**
      * Maximum difference in lengths between a matched word and the stemmed variant it matched
      * against.
@@ -50,7 +58,8 @@ private class Geary.ImapDB.SearchQuery : Geary.SearchQuery {
      * This prevents long words being matched to short stem variants (which creates opportunities
      * for greedy matching).
      *
-     * Overridden by {@link allow_stemming}.  Determined by {@link strategy}.
+     * Overridden by {@link allow_stemming}. Determined by the {@link
+     * Geary.SearchQuery.Strategy} passed to the constructor.
      */
     public int max_difference_match_stem_lengths { get; private set; }
 
diff --git a/src/engine/imap-engine/imap-engine-generic-account.vala 
b/src/engine/imap-engine/imap-engine-generic-account.vala
index 2ac8e73..3f6d2d2 100644
--- a/src/engine/imap-engine/imap-engine-generic-account.vala
+++ b/src/engine/imap-engine/imap-engine-generic-account.vala
@@ -597,20 +597,25 @@ private abstract class Geary.ImapEngine.GenericAccount : Geary.Account {
     }
     
     /**
-     * Returns an Imap.Folder that is not connected (is detached) to a MinimalFolder or any other
-     * ImapEngine container.
+     * Returns an Imap.Folder that is not connected (is detached) to a
+     * MinimalFolder or any other ImapEngine container.
      *
-     * This is useful for one-shot operations that need to bypass the heavyweight synchronization
-     * routines inside MinimalFolder.  This also means that operations performed on this Folder will
-     * not be reflected in the local database unless there's a separate connection to the server
-     * that is notified or detects these changes.
+     * This is useful for one-shot operations that need to bypass the
+     * heavyweight synchronization routines inside MinimalFolder.
+     * This also means that operations performed on this Folder will
+     * not be reflected in the local database unless there's a
+     * separate connection to the server that is notified or detects
+     * these changes.
      *
-     * The returned Folder must be opened prior to use and closed once completed.  ''Leaving a
-     * Folder open will cause a connection leak.''
+     * The returned Folder must be opened prior to use and closed once
+     * completed.
      *
-     * It is not recommended this object be held open long-term, or that its status or notifications
-     * be directly written to the database unless you know exactly what you're doing.  ''Caveat
-     * implementor.''
+     * ''Leaving a Folder open will cause a connection leak.''
+     *
+     * It is not recommended this object be held open long-term, or
+     * that its status or notifications be directly written to the
+     * database unless you know exactly what you're doing.
+     * ''Caveat implementor.''
      */
     public async Imap.Folder fetch_detached_folder_async(Geary.FolderPath path, Cancellable? cancellable)
         throws Error {
diff --git a/src/engine/imap-engine/imap-engine-replay-operation.vala 
b/src/engine/imap-engine/imap-engine-replay-operation.vala
index eb1aef4..36ecb99 100644
--- a/src/engine/imap-engine/imap-engine-replay-operation.vala
+++ b/src/engine/imap-engine/imap-engine-replay-operation.vala
@@ -1,40 +1,50 @@
-/* Copyright 2016 Software Freedom Conservancy Inc.
+/*
+ * Copyright 2016 Software Freedom Conservancy Inc.
  *
  * This software is licensed under the GNU Lesser General Public License
  * (version 2.1 or later).  See the COPYING file in this distribution.
  */
 
+/**
+ * Base class for folder operations executed by {@link ReplayQueue}.
+ */
 private abstract class Geary.ImapEngine.ReplayOperation : Geary.BaseObject, Gee.Comparable<ReplayOperation> {
+
     /**
-     * Scope specifies what type of operations (remote, local, or both) are needed by this operation.
-     *
-     * What methods are made on the operation depends on the returned Scope:
-     *
-     * LOCAL_AND_REMOTE: replay_local_async() is called.  If that method returns COMPLETED,
-     *   no further calls are made.  If it returns CONTINUE, replay_remote_async() is called.
-     * LOCAL_ONLY: replay_local_async() only.  replay_remote_async() will never be called.
-     * REMOTE_ONLY: replay_remote_async() only.  replay_local_async() will never be called.
-     *
-     * See the various replay methods for how backout_local_async() may be called depending on
-     * this field and those methods' return values.
+     * Specifies the call scope (local, remote, both) of an operation.
+     *
+     * The methods that are called for the operation depends on the
+     * returned Scope.
+     *
+     * * `LOCAL_AND_REMOTE`: replay_local_async() is called.  If that
+     * method returns COMPLETED, no further calls are made.  If it
+     * returns CONTINUE, replay_remote_async() is called.
+     * * `LOCAL_ONLY`: replay_local_async() only.
+     * replay_remote_async() will never be called.
+     * * `REMOTE_ONLY`: replay_remote_async() only.
+     * replay_local_async() will never be called.
+     *
+     * See the various replay methods for how backout_local_async()
+     * may be called depending on this field and those methods' return
+     * values.
      */
     public enum Scope {
         LOCAL_AND_REMOTE,
         LOCAL_ONLY,
         REMOTE_ONLY
     }
-    
+
     public enum Status {
         COMPLETED,
         CONTINUE
     }
-    
+
     public enum OnError {
         THROW,
         RETRY,
         IGNORE
     }
-    
+
     public string name { get; set; }
     public int64 submission_number { get; set; default = -1; }
     public Scope scope { get; private set; }
@@ -99,28 +109,30 @@ private abstract class Geary.ImapEngine.ReplayOperation : Geary.BaseObject, Gee.
     /**
      * See Scope for conditions where this method will be called.
      *
-     * Returns:
-     *   COMPLETED: the operation has completed and no further calls should be made.
-     *   CONTINUE: The local operation has completed and the remote portion must be executed as
-     *      well.  This is treated as COMPLETED if get_scope() returns LOCAL_ONLY.
+     * If an error is thrown, {@link backout_local_async} will will
+     * *not* be executed.
      *
-     * If Error thrown:
-     *   backout_local_async() will *not* be executed.
+     * @return {@link Status.COMPLETED} if the operation has completed
+     * and no further calls should be made, else {@link
+     * Status.CONTINUE} if the local operation has completed and the
+     * remote portion must be executed as well. This is treated as
+     * `COMPLETED` if get_scope() returns {@link Scope.LOCAL_ONLY}.
      */
     public abstract async Status replay_local_async() throws Error;
-    
+
     /**
      * See Scope for conditions where this method will be called.
      *
-     * Returns:
-     *   COMPLETED: the operation has completed and no further calls should be made.
-     *   CONTINUE: Treated as COMPLETED.
+     * If an error is thrown, {@link backout_local_async} will be
+     * executed only if scope is LOCAL_AND_REMOTE.
+     *
+     * @return {@link Status.COMPLETED} if the operation has completed
+     * and no further calls should be made, else {@link
+     * Status.CONTINUE} if treated as `COMPLETED`.
      *
-     * If Error thrown:
-     *   backout_local_async() will be executed only if scope is LOCAL_AND_REMOTE.
      */
     public abstract async Status replay_remote_async() throws Error;
-    
+
     /**
      * See Scope, replay_local_async(), and replay_remote_async() for conditions for this where this
      * will be called.
diff --git a/src/engine/imap-engine/replay-ops/imap-engine-move-email-prepare.vala 
b/src/engine/imap-engine/replay-ops/imap-engine-move-email-prepare.vala
index 30b1875..4b4dde4 100644
--- a/src/engine/imap-engine/replay-ops/imap-engine-move-email-prepare.vala
+++ b/src/engine/imap-engine/replay-ops/imap-engine-move-email-prepare.vala
@@ -1,14 +1,17 @@
-/* Copyright 2016 Software Freedom Conservancy Inc.
+/*
+ * Copyright 2016 Software Freedom Conservancy Inc.
  *
  * This software is licensed under the GNU Lesser General Public License
  * (version 2.1 or later).  See the COPYING file in this distribution.
  */
 
 /**
- * Stage one of a {@link RevokableMove}: collect valid {@link ImapDB.EmailIdentifiers}, mark
- * messages as removed, and update counts.
+ * Stage one of a {@link RevokableMove}.
+ *
+ * This operation collects valid {@link ImapDB.EmailIdentifier}s for
+ * messages to be removed, mark the messages as removed, and update
+ * counts.
  */
-
 private class Geary.ImapEngine.MoveEmailPrepare : Geary.ImapEngine.SendReplayOperation {
     public Gee.Set<ImapDB.EmailIdentifier>? prepared_for_move = null;
     
diff --git a/src/engine/imap/api/imap-account.vala b/src/engine/imap/api/imap-account.vala
index 8ecfb12..40d12eb 100644
--- a/src/engine/imap/api/imap-account.vala
+++ b/src/engine/imap/api/imap-account.vala
@@ -10,8 +10,8 @@
  *
  * Because of the complexities of the IMAP protocol, this private
  * class takes common operations that a Geary.Account implementation
- * would need (in particular, {@link Geary.ImapEngine.Account} and
- * makes them into simple async calls.
+ * would need (in particular, {@link Geary.ImapEngine.GenericAccount}
+ * and makes them into simple async calls.
  *
  * Geary.Imap.Account manages the {@link Imap.Folder} objects it
  * returns, but only in the sense that it will not create new
diff --git a/src/engine/imap/api/imap-folder.vala b/src/engine/imap/api/imap-folder.vala
index c0bd773..d3e65e6 100644
--- a/src/engine/imap/api/imap-folder.vala
+++ b/src/engine/imap/api/imap-folder.vala
@@ -31,9 +31,10 @@ private class Geary.Imap.Folder : BaseObject {
     public Trillian accepts_user_flags { get; private set; default = Trillian.UNKNOWN; }
 
     /**
-     * Set to true when it's detected that the server doesn't allow a space between "header.fields"
-     * and the list of email headers to be requested via FETCH; see
-     * https://bugzilla.gnome.org/show_bug.cgi?id=714902
+     * Set to true when it's detected that the server doesn't allow a
+     * space between "header.fields" and the list of email headers to
+     * be requested via FETCH; see:
+     * [[https://bugzilla.gnome.org/show_bug.cgi?id=714902|Bug * 714902]]
      */
     public bool imap_header_fields_hack { get; private set; default = false; }
 
diff --git a/src/engine/imap/command/imap-namespace-command.vala 
b/src/engine/imap/command/imap-namespace-command.vala
index 2402d46..8cf26b2 100644
--- a/src/engine/imap/command/imap-namespace-command.vala
+++ b/src/engine/imap/command/imap-namespace-command.vala
@@ -11,7 +11,7 @@
  * Determines the mailbox name prefix and hierarchy delimiter for the
  * personal, other user's and public namespaces.
  *
- * @see [[https://tools.ietf.org/html/rfc2342]]
+ * See [[https://tools.ietf.org/html/rfc2342|RFC 2342]] for details.
  */
 public class Geary.Imap.NamespaceCommand : Command {
 
diff --git a/src/engine/imap/message/imap-mailbox-specifier.vala 
b/src/engine/imap/message/imap-mailbox-specifier.vala
index 7df741e..ce34d3d 100644
--- a/src/engine/imap/message/imap-mailbox-specifier.vala
+++ b/src/engine/imap/message/imap-mailbox-specifier.vala
@@ -1,4 +1,5 @@
-/* Copyright 2016 Software Freedom Conservancy Inc.
+/*
+ * Copyright 2016 Software Freedom Conservancy Inc.
  *
  * This software is licensed under the GNU Lesser General Public License
  * (version 2.1 or later).  See the COPYING file in this distribution.
@@ -11,12 +12,16 @@
  *
  * See [[http://tools.ietf.org/html/rfc3501#section-5.1]]
  */
-
 public class Geary.Imap.MailboxSpecifier : BaseObject, Gee.Hashable<MailboxSpecifier>, 
Gee.Comparable<MailboxSpecifier> {
-    // all references to Inbox are converted to this string, purely for sanity sake when dealing
-    // with Inbox's case issues
+
+    /**
+     * Canonical name used for the IMAP Inbox for an account.
+     *
+     * All references to Inbox are converted to this string, purely
+     * for sanity sake when dealing with Inbox's case issues.
+     */
     public const string CANONICAL_INBOX_NAME = "INBOX";
-    
+
     /**
      * An instance of an Inbox MailboxSpecifier.
      *
diff --git a/src/engine/rfc822/rfc822-message.vala b/src/engine/rfc822/rfc822-message.vala
index 267203a..b374dc4 100644
--- a/src/engine/rfc822/rfc822-message.vala
+++ b/src/engine/rfc822/rfc822-message.vala
@@ -623,7 +623,7 @@ public class Geary.RFC822.Message : BaseObject {
      * The initial call should pass the root of this message and UNSPECIFIED as its container
      * subtype.
      *
-     * @returns Whether a text part with the desired text_subtype was found
+     * @return Whether a text part with the desired text_subtype was found
      */
     private bool construct_body_from_mime_parts(GMime.Object node, Mime.MultipartSubtype container_subtype,
         string text_subtype, bool to_html, InlinePartReplacer? replacer, ref string? body) throws 
RFC822Error {
diff --git a/src/engine/util/util-idle-manager.vala b/src/engine/util/util-idle-manager.vala
index fac46dc..43f2ab3 100644
--- a/src/engine/util/util-idle-manager.vala
+++ b/src/engine/util/util-idle-manager.vala
@@ -51,7 +51,7 @@ public class Geary.IdleManager : BaseObject {
      * Constructs a new idle manager with an interval in seconds.
      *
      * The idle function will be by default not running, and hence
-     * needs to be started by a call to {@link start}.
+     * needs to be started by a call to {@link schedule}.
      */
     public IdleManager(IdleFunc callback) {
         this.callback = callback;
diff --git a/src/meson.build b/src/meson.build
index 75da996..103502e 100644
--- a/src/meson.build
+++ b/src/meson.build
@@ -81,12 +81,13 @@ geary_bin = executable('geary',
 if enable_valadoc
   geary_docs = custom_target('valadoc',
     build_by_default: true,
+    depends: geary_engine_lib,
     input: geary_engine_sources,
-    output: 'docs',
+    output: 'valadoc',
     command: [ valadoc,
       '--verbose',
       '--force',
-      '--deps',
+      '--internal',
       '--package-name=@0@-@1@'.format(meson.project_name(), meson.project_version()),
       '--package-version=@0@'.format(meson.project_version()),
       '--target-glib=@0@'.format(target_glib),
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]