[geary] Fix Valadoc: Bug #714502

From: Jim Nelson <jnelson src gnome org>
To: commits-list gnome org
Cc:
Subject: [geary] Fix Valadoc: Bug #714502
Date: Thu, 12 Mar 2015 01:16:39 +0000 (UTC)
commit a947fc2fed053551f3ecd546714946379d941e7c
Author: Jim Nelson <jim yorba org>
Date:   Wed Mar 11 18:11:48 2015 -0700

    Fix Valadoc: Bug #714502
    
    This cleans up Valadoc comments so latest Valadoc doesn't issue errors
    or warnings.

 src/CMakeLists.txt                                 |    2 +-
 src/engine/api/geary-account-information.vala      |    2 +-
 src/engine/api/geary-account.vala                  |   13 ++++++----
 src/engine/api/geary-attachment.vala               |    2 +-
 src/engine/api/geary-folder-path.vala              |    2 +-
 src/engine/api/geary-folder-properties.vala        |   26 ++++++++++++-------
 src/engine/api/geary-folder-supports-archive.vala  |    2 +-
 src/engine/api/geary-folder-supports-create.vala   |    2 +
 src/engine/api/geary-folder-supports-move.vala     |    2 +-
 src/engine/api/geary-progress-monitor.vala         |    4 +-
 src/engine/app/app-conversation.vala               |    2 +-
 src/engine/app/app-draft-manager.vala              |   12 ++++----
 src/engine/db/db-connection.vala                   |    2 +-
 src/engine/imap/api/imap-folder-properties.vala    |    3 +-
 src/engine/imap/command/imap-list-command.vala     |    2 +-
 .../imap/command/imap-list-return-parameter.vala   |    2 +-
 src/engine/imap/command/imap-message-set.vala      |    2 +-
 .../message/imap-fetch-body-data-specifier.vala    |   16 +++++++-----
 .../imap/message/imap-fetch-data-specifier.vala    |   12 ++++-----
 src/engine/imap/message/imap-sequence-number.vala  |    8 +++---
 src/engine/imap/message/imap-uid-validity.vala     |    2 +-
 src/engine/imap/message/imap-uid.vala              |    2 +-
 src/engine/imap/parameter/imap-list-parameter.vala |    2 +-
 .../imap/parameter/imap-number-parameter.vala      |    2 +-
 .../imap/parameter/imap-string-parameter.vala      |   14 ++++++----
 src/engine/imap/response/imap-capabilities.vala    |    2 +-
 src/engine/imap/response/imap-fetched-data.vala    |    6 ++--
 src/engine/mime/mime-content-disposition.vala      |    2 +-
 src/engine/mime/mime-content-parameters.vala       |    8 +++---
 src/engine/mime/mime-content-type.vala             |    4 +-
 src/engine/nonblocking/nonblocking-variants.vala   |    6 ++--
 src/engine/rfc822/rfc822-mailbox-addresses.vala    |    2 +-
 src/engine/rfc822/rfc822-message.vala              |    2 +-
 src/engine/util/util-synchronization.vala          |    8 +----
 34 files changed, 95 insertions(+), 85 deletions(-)
---
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index 74bea83..bd0d5ee 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -746,7 +746,7 @@ add_custom_target(
     WORKING_DIRECTORY
         ${CMAKE_SOURCE_DIR}/src
     COMMAND
-        ${VALADOC_EXECUTABLE} --force --no-protected -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
+        ${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
 )
 
 ## Make clean: remove copied files
diff --git a/src/engine/api/geary-account-information.vala b/src/engine/api/geary-account-information.vala
index 2623cb0..0387503 100644
--- a/src/engine/api/geary-account-information.vala
+++ b/src/engine/api/geary-account-information.vala
@@ -66,7 +66,7 @@ public class Geary.AccountInformation : BaseObject {
     //
     
     /**
-     * User's name for the { link primary_mailbox}.
+     * User's name for the { link get_primary_mailbox_address}.
      */
     public string real_name { get; set; }
     
diff --git a/src/engine/api/geary-account.vala b/src/engine/api/geary-account.vala
index 1b5d72a..69eac87 100644
--- a/src/engine/api/geary-account.vala
+++ b/src/engine/api/geary-account.vala
@@ -232,11 +232,14 @@ public abstract class Geary.Account : BaseObject {
     /**
      * Rebuild the local data stores for this { link Account}.
      *
-     * This should only be used if { link open_async} throws { link EngineError.CORRUPTION},
-     * indicating that the local data store is corrupted and cannot be used.  ''rebuild_async()
-     * will delete all local data''.  If the Account is backed by a synchronized copy on the
-     * network, it will rebuild its local mail store.  If not, the data is forever deleted.
-     * Hence, it's best to query the user before calling this method.
+     * This should only be used if { link open_async} throws { link EngineError.CORRUPT},
+     * indicating that the local data store is corrupted and cannot be used.
+     *
+     * ''rebuild_async() will delete all local data''.
+     *
+     * If the Account is backed by a synchronized copy on the network, it will rebuild its local
+     * mail store.  If not, the data is forever deleted.  Hence, it's best to query the user before
+     * calling this method.
      *
      * Unlike most methods in Account, this should only be called when the Account is closed.
      */
diff --git a/src/engine/api/geary-attachment.vala b/src/engine/api/geary-attachment.vala
index a34f93f..4b3703a 100644
--- a/src/engine/api/geary-attachment.vala
+++ b/src/engine/api/geary-attachment.vala
@@ -43,7 +43,7 @@ public abstract class Geary.Attachment : BaseObject {
     public int64 filesize { get; private set; }
     
     /**
-     * The { link Disposition} of the attachment, as specified by the { link Email}.
+     * The { link Mime.ContentDisposition} of the attachment, as specified by the { link Email}.
      *
      * See [[https://tools.ietf.org/html/rfc2183]]
      */
diff --git a/src/engine/api/geary-folder-path.vala b/src/engine/api/geary-folder-path.vala
index d0ac0b9..4350c55 100644
--- a/src/engine/api/geary-folder-path.vala
+++ b/src/engine/api/geary-folder-path.vala
@@ -364,7 +364,7 @@ public abstract class Geary.FolderRoot : Geary.FolderPath {
      * The default case sensitivity of each element in the { link FolderPath}.
      *
      * @see FolderRoot.case_sensitive
-     * @see FolderRoot.get_child
+     * @see FolderPath.get_child
      */
     public bool default_case_sensitivity { get; private set; }
     
diff --git a/src/engine/api/geary-folder-properties.vala b/src/engine/api/geary-folder-properties.vala
index b14f51c..be1a24b 100644
--- a/src/engine/api/geary-folder-properties.vala
+++ b/src/engine/api/geary-folder-properties.vala
@@ -14,29 +14,32 @@ public abstract class Geary.FolderProperties : BaseObject {
     public const string PROP_NAME_IS_VIRTUAL = "is-virtual";
     
     /**
-     * The total count of email in the Folder.
+     * The total count of email in the { link Folder}.
      */
     public int email_total { get; protected set; }
     
     /**
-     * The total count of unread email in the Folder.
+     * The total count of unread email in the { link Folder}.
      */
     public int email_unread { get; protected set; }
     
     /**
-     * Returns a Trillian indicating if this Folder has children.  has_children == Trillian.TRUE
-     * implies supports_children == Trilian.TRUE.
+     * Returns a { link Trillian} indicating if this { link Folder} has children.
+     *
+     * has_children == { link Trillian.TRUE} implies { link supports_children} == Trilian.TRUE.
      */
     public Trillian has_children { get; protected set; }
     
     /**
-     * Returns a Trillian indicating if this Folder can parent new children Folders.  This does
-     * *not* mean creating a sub-folder is guaranteed to succeed.
+     * Returns a { link Trillian} indicating if this { link Folder} can parent new children
+     * { link Folder}s.
+     *
+     * This does ''not'' mean creating a sub-folder is guaranteed to succeed.
      */
     public Trillian supports_children { get; protected set; }
     
     /**
-     * Returns a Trillian indicating if Folder.open_async() *can* succeed remotely.
+     * Returns a { link Trillian} indicating if { link Folder.open_async} can succeed remotely.
      */
     public Trillian is_openable { get; protected set; }
     
@@ -60,9 +63,12 @@ public abstract class Geary.FolderProperties : BaseObject {
     public bool is_virtual { get; private set; }
     
     /**
-     * True if APPEND on the folder will never return the created UID.  This is
-     * for servers that don't support UIDPLUS.  Most servers support UIDPLUS,
-     * so this will usually be false.
+     * True if the { link Folder} offers the { link FolderSupport.Create} interface but is
+     * guaranteed not to return a { link EmailIdentifier}, even if
+     * { link FolderSupport.Create.create_email_async} succeeds.
+     *
+     * This is for IMAP servers that don't support UIDPLUS.  Most servers support UIDPLUS, so this
+     * will usually be false.
      */
     public bool create_never_returns_id { get; protected set; }
     
diff --git a/src/engine/api/geary-folder-supports-archive.vala 
b/src/engine/api/geary-folder-supports-archive.vala
index 4ef8a9f..91b7cac 100644
--- a/src/engine/api/geary-folder-supports-archive.vala
+++ b/src/engine/api/geary-folder-supports-archive.vala
@@ -20,7 +20,7 @@ public interface Geary.FolderSupport.Archive : Geary.Folder {
      *
      * The { link Geary.Folder} must be opened prior to attempting this operation.
      *
-     * @returns A { link Geary.Revokable} that may be used to revoke (undo) this operation later.
+     * @return A { link Geary.Revokable} that may be used to revoke (undo) this operation later.
      */
     public abstract async Geary.Revokable? archive_email_async(Gee.List<Geary.EmailIdentifier> email_ids,
         Cancellable? cancellable = null) throws Error;
diff --git a/src/engine/api/geary-folder-supports-create.vala 
b/src/engine/api/geary-folder-supports-create.vala
index 7565515..ec38e97 100644
--- a/src/engine/api/geary-folder-supports-create.vala
+++ b/src/engine/api/geary-folder-supports-create.vala
@@ -28,6 +28,8 @@ public interface Geary.FolderSupport.Create : Geary.Folder {
      * 
      * If an id is passed, this will replace the existing message by deleting it after the new
      * message is created.  The new message's ID is returned.
+     *
+     * @see FolderProperties.create_never_returns_id
      */
     public abstract async Geary.EmailIdentifier? create_email_async(Geary.RFC822.Message rfc822, EmailFlags? 
flags,
         DateTime? date_received, Geary.EmailIdentifier? id, Cancellable? cancellable = null) throws Error;
diff --git a/src/engine/api/geary-folder-supports-move.vala b/src/engine/api/geary-folder-supports-move.vala
index d0d8de6..e6c2534 100644
--- a/src/engine/api/geary-folder-supports-move.vala
+++ b/src/engine/api/geary-folder-supports-move.vala
@@ -21,7 +21,7 @@ public interface Geary.FolderSupport.Move : Geary.Folder {
      *
      * The { link Geary.Folder} must be opened prior to attempting this operation.
      *
-     * @returns A { link Geary.Revokable} that may be used to revoke (undo) this operation later.
+     * @return A { link Geary.Revokable} that may be used to revoke (undo) this operation later.
      */
     public abstract async Geary.Revokable? move_email_async(Gee.List<Geary.EmailIdentifier> to_move,
         Geary.FolderPath destination, Cancellable? cancellable = null) throws Error;
diff --git a/src/engine/api/geary-progress-monitor.vala b/src/engine/api/geary-progress-monitor.vala
index e2b371b..e1db70e 100644
--- a/src/engine/api/geary-progress-monitor.vala
+++ b/src/engine/api/geary-progress-monitor.vala
@@ -83,7 +83,7 @@ public class Geary.ReentrantProgressMonitor : Geary.ProgressMonitor {
     }
     
     /**
-     * @inheritDoc
+     * { inheritDoc}
      *
      * Unlike the base class implementation, this may be called multiple times successively without
      * a problem, but each must be matched by a { link notify_finish} to completely stop the
@@ -97,7 +97,7 @@ public class Geary.ReentrantProgressMonitor : Geary.ProgressMonitor {
     }
     
     /**
-     * @inheritDoc
+     * { inheritDoc}
      *
      * Unlike the base class implementation, this may be called multiple times successively as
      * long as they were matched by a prior { link notify_start}.
diff --git a/src/engine/app/app-conversation.vala b/src/engine/app/app-conversation.vala
index 60a3905..a5afd8e 100644
--- a/src/engine/app/app-conversation.vala
+++ b/src/engine/app/app-conversation.vala
@@ -21,7 +21,7 @@ public class Geary.App.Conversation : BaseObject {
     
     /**
      * Specify the location of the { link Email} in relation to the { link Folder} being monitored
-     * by the { link Converation}'s { link ConversationMonitor}.
+     * by the { link Conversation}'s { link ConversationMonitor}.
      *
      * IN_FOLDER represents Email that is found in the Folder the ConversationMonitor is
      * monitoring.  OUT_OF_FOLDER means the Email is located elsewhere in the { link Account}.
diff --git a/src/engine/app/app-draft-manager.vala b/src/engine/app/app-draft-manager.vala
index 6489f98..8838949 100644
--- a/src/engine/app/app-draft-manager.vala
+++ b/src/engine/app/app-draft-manager.vala
@@ -80,7 +80,7 @@ public class Geary.App.DraftManager : BaseObject {
     }
     
     /**
-     * Indicates the { link DraftsManager} is open and ready for service.
+     * Indicates the { link DraftManager} is open and ready for service.
      *
      * Although this property can be monitored, the object is considered "open" when
      * { link open_async} completes, not when this property changes to true.
@@ -255,7 +255,7 @@ public class Geary.App.DraftManager : BaseObject {
     }
     
     /**
-     * Flush pending operations and close the { link DraftsManager}.
+     * Flush pending operations and close the { link DraftManager}.
      *
      * Once closed, the object cannot be opened again.  Create a new object in that case.
      *
@@ -316,8 +316,8 @@ public class Geary.App.DraftManager : BaseObject {
      * See { link FolderSupport.Create.create_email_async} for more information on the flags and
      * date_received arguments.
      *
-     * @returns A { link Semaphore} that is notified when the operation completes (with or without
-     * error)
+     * @return A { link Nonblocking.Semaphore} that is notified when the operation completes (with
+     * or without error)
      */
     public Geary.Nonblocking.Semaphore? update(Geary.RFC822.Message draft, Geary.EmailFlags? flags,
         DateTime? date_received) throws Error {
@@ -335,8 +335,8 @@ public class Geary.App.DraftManager : BaseObject {
      * Note: Replaced drafts are deleted, but on some services (i.e. Gmail) those deleted messages
      * are actually moved to the Trash.  This call does not currently solve that problem.
      *
-     * @returns A { link Semaphore} that is notified when the operation completes (with or without
-     * error)
+     * @return A { link Nonblocking.Semaphore} that is notified when the operation completes (with
+     * or without error)
      */
     public Geary.Nonblocking.Semaphore? discard() throws Error {
         check_open();
diff --git a/src/engine/db/db-connection.vala b/src/engine/db/db-connection.vala
index af22a88..4a1eabf 100644
--- a/src/engine/db/db-connection.vala
+++ b/src/engine/db/db-connection.vala
@@ -257,7 +257,7 @@ public class Geary.Db.Connection : Geary.Db.Context {
      *
      * A new database has a user version number of zero.
      *
-     * @see set_user_version_number().
+     * @see set_user_version_number
      */
     public int get_user_version_number() throws Error {
         return get_pragma_int(PRAGMA_USER_VERSION);
diff --git a/src/engine/imap/api/imap-folder-properties.vala b/src/engine/imap/api/imap-folder-properties.vala
index 0554848..14371ea 100644
--- a/src/engine/imap/api/imap-folder-properties.vala
+++ b/src/engine/imap/api/imap-folder-properties.vala
@@ -172,7 +172,8 @@ public class Geary.Imap.FolderProperties : Geary.FolderProperties {
     /**
      * Update an existing { link FolderProperties} with fresh { link StatusData}.
      *
-     * This will force the { link email_total} property to match the { link status_messages} value.
+     * This will force the { link Geary.FolderProperties.email_total} property to match the
+     * { link status_messages} value.
      */
     public void update_status(StatusData status) {
         set_status_message_count(status.messages, true);
diff --git a/src/engine/imap/command/imap-list-command.vala b/src/engine/imap/command/imap-list-command.vala
index f70bf86..8999f4b 100644
--- a/src/engine/imap/command/imap-list-command.vala
+++ b/src/engine/imap/command/imap-list-command.vala
@@ -31,7 +31,7 @@ public class Geary.Imap.ListCommand : Command {
      * LIST "" % -> "Spam"
      * LIST "" "Spam" -> "~spam"
      *
-     * See http://redmine.yorba.org/issues/7624 for more information.
+     * See [[http://redmine.yorba.org/issues/7624]] for more information.
      */
     public ListCommand(MailboxSpecifier mailbox, bool use_xlist, ListReturnParameter? return_param) {
         base (use_xlist ? XLIST_NAME : NAME, { "" });
diff --git a/src/engine/imap/command/imap-list-return-parameter.vala 
b/src/engine/imap/command/imap-list-return-parameter.vala
index 87fe8b8..0573a56 100644
--- a/src/engine/imap/command/imap-list-return-parameter.vala
+++ b/src/engine/imap/command/imap-list-return-parameter.vala
@@ -17,7 +17,7 @@
 
 public class Geary.Imap.ListReturnParameter : ListParameter {
     /**
-     * See https://tools.ietf.org/html/rfc6154
+     * See [[https://tools.ietf.org/html/rfc6154]]
      */
     public const string SPECIAL_USE = "special-use";
     
diff --git a/src/engine/imap/command/imap-message-set.vala b/src/engine/imap/command/imap-message-set.vala
index 114dd1a..107e696 100644
--- a/src/engine/imap/command/imap-message-set.vala
+++ b/src/engine/imap/command/imap-message-set.vala
@@ -113,7 +113,7 @@ public class Geary.Imap.MessageSet : BaseObject {
     /**
      * Parses a string representing a { link MessageSet} into a List of { link SequenceNumber}s.
      *
-     * See the note at { link parse_uid} about limitations of this method.
+     * See the note at { link uid_parse} about limitations of this method.
      *
      * Returns null if the string or parsed set is empty.
      *
diff --git a/src/engine/imap/message/imap-fetch-body-data-specifier.vala 
b/src/engine/imap/message/imap-fetch-body-data-specifier.vala
index 781c9d4..7f98fab 100644
--- a/src/engine/imap/message/imap-fetch-body-data-specifier.vala
+++ b/src/engine/imap/message/imap-fetch-body-data-specifier.vala
@@ -8,7 +8,7 @@
  * A symbolic representation of IMAP FETCH's BODY section parameter.
  *
  * This is only used with { link FetchCommand}.  Most IMAP FETCH calls can be achieved with
- * plain { link FetchDataType} specifiers.  Some cannot, however, and this more complicated
+ * plain { link FetchDataSpecifier}s.  Some cannot, however, and this more complicated
  * specifier must be used.
  *
  * A fully-qualified specifier looks something like this for requests:
@@ -34,7 +34,7 @@
  * BODY[<section>]<<partial>>, and [[http://tools.ietf.org/html/rfc3501#section-7.4.2]],
  * specifically section on BODY[<section>]<<origin octet>>.
  *
- * @see FetchDataType
+ * @see FetchDataSpecifier
  */
 
 public class Geary.Imap.FetchBodyDataSpecifier : BaseObject, Gee.Hashable<FetchBodyDataSpecifier> {
@@ -196,7 +196,7 @@ public class Geary.Imap.FetchBodyDataSpecifier : BaseObject, Gee.Hashable<FetchB
     }
     
     /**
-     * Returns the { link FetchBodyDataType} in a string ready for a { link Command}.
+     * Returns the { link FetchBodyDataSpecifier} in a string ready for a { link Command}.
      *
      * The serialized field names are returned in a case-insensitive casefolded order.
      * (Some servers return field names in arbitrary order.)
@@ -210,7 +210,7 @@ public class Geary.Imap.FetchBodyDataSpecifier : BaseObject, Gee.Hashable<FetchB
     }
     
     /**
-     * Returns the { link FetchBodyDataType} in a string as it might appear in a
+     * Returns the { link FetchBodyDataSpecifier} in a string as it might appear in a
      * { link ServerResponse}.
      *
      * The FetchBodyDataType server response does not include the peek modifier or the span
@@ -280,10 +280,12 @@ public class Geary.Imap.FetchBodyDataSpecifier : BaseObject, Gee.Hashable<FetchB
     }
     
     /**
-     * Returns true if the { link StringParameter} is formatted like a { link FetchBodyDataType}.
+     * Returns true if the { link StringParameter} is formatted like a
+     * { link FetchBodyDataSpecifier}.
      *
-     * This method doesn't do a full test.  It's possible for { link deserialize_response} to
-     * throw an exception if this method returns true.
+     * This method doesn't do a //full// test.  It's possible for { link deserialize_response} to
+     * throw an exception if this method returns true.  This method should be used for simple
+     * identification when parsing and then catch the exception as the final word on validity.
      *
      * @see deserialize_response
      */
diff --git a/src/engine/imap/message/imap-fetch-data-specifier.vala 
b/src/engine/imap/message/imap-fetch-data-specifier.vala
index c95341e..2bbcdc0 100644
--- a/src/engine/imap/message/imap-fetch-data-specifier.vala
+++ b/src/engine/imap/message/imap-fetch-data-specifier.vala
@@ -9,11 +9,11 @@
  *
  * Most FETCH requests can use this simple specifier to return various parts of the message.
  * More complicated requests (and requests for partial header or body sections) must use a
- * { link FetchBodyDataType} specifier.
+ * { link FetchBodyDataSpecifier} specifier.
  *
  * See [[http://tools.ietf.org/html/rfc3501#section-6.4.5]]
  *
- * @see FetchBodyDataType
+ * @see FetchBodyDataSpecifier
  */
 
 public enum Geary.Imap.FetchDataSpecifier {
@@ -78,9 +78,7 @@ public enum Geary.Imap.FetchDataSpecifier {
     }
     
     /**
-     * Decoders a { link StringParameter} into a { link FetchDataType} using { link decode}.
-     *
-     * @see decode
+     * Decodes a { link StringParameter} into a { link FetchDataSpecifier}.
      */
     public static FetchDataSpecifier from_parameter(StringParameter strparam) throws ImapError {
         switch (strparam.as_lower()) {
@@ -130,14 +128,14 @@ public enum Geary.Imap.FetchDataSpecifier {
     }
     
     /**
-     * Turns this { link FetchDataType} into a { link StringParameter} for transmission.
+     * Turns this { link FetchDataSpecifier} into a { link StringParameter} for transmission.
      */
     public StringParameter to_parameter() {
         return new AtomParameter(to_string());
     }
     
     /**
-     * Returns the appropriate { link FetchDataDecoder} for this { link FetchDataType}.
+     * Returns the appropriate { link FetchDataDecoder} for this { link FetchDataSpecifier}.
      *
      * The FetchDataDecoder can then be used to convert the associated { link Parameter}s into
      * { link Imap.MessageData}.
diff --git a/src/engine/imap/message/imap-sequence-number.vala 
b/src/engine/imap/message/imap-sequence-number.vala
index a4957c4..7de206f 100644
--- a/src/engine/imap/message/imap-sequence-number.vala
+++ b/src/engine/imap/message/imap-sequence-number.vala
@@ -32,7 +32,7 @@ public class Geary.Imap.SequenceNumber : Geary.MessageData.Int64MessageData, Gea
      * This does not check if the value is valid.
      *
      * @see is_value_valid
-     * @see SequenceNumber.checked
+     * @see SequenceNumber.SequenceNumber.checked
      */
     public SequenceNumber(int64 value) {
         base (value);
@@ -53,14 +53,14 @@ public class Geary.Imap.SequenceNumber : Geary.MessageData.Int64MessageData, Gea
     }
     
     /**
-     * Defined as { link value} >= { link MIN} and <= { link MAX}.
+     * Defined as { link MessageData.Int64MessageData.value} >= { link MIN} and <= { link MAX}.
      */
     public static bool is_value_valid(int64 value) {
         return value >= MIN && value <= MAX;
     }
     
     /**
-     * Defined as { link value} >= { link MIN} and <= { link MAX}.
+     * Defined as { link MessageData.Int64MessageData.value} >= { link MIN} and <= { link MAX}.
      */
     public bool is_valid() {
         return is_value_valid(value);
@@ -69,7 +69,7 @@ public class Geary.Imap.SequenceNumber : Geary.MessageData.Int64MessageData, Gea
     /**
      * Returns a new { link SequenceNumber} that is one lower than this value.
      *
-     * Returns null if the decremented value is less than { link MIN_VALUE}.
+     * Returns null if the decremented value is less than { link MIN}.
      */
     public SequenceNumber? dec() {
         return (value > MIN) ? new SequenceNumber(value - 1) : null;
diff --git a/src/engine/imap/message/imap-uid-validity.vala b/src/engine/imap/message/imap-uid-validity.vala
index 7df7aa4..4c53e06 100644
--- a/src/engine/imap/message/imap-uid-validity.vala
+++ b/src/engine/imap/message/imap-uid-validity.vala
@@ -31,7 +31,7 @@ public class Geary.Imap.UIDValidity : Geary.MessageData.Int64MessageData, Geary.
     /**
      * Creates a new { link UIDValidity} without checking for valid values.
      *
-     * @see UIDValidity.checked
+     * @see UIDValidity.UIDValidity.checked
      */
     public UIDValidity(int64 value) {
         base (value);
diff --git a/src/engine/imap/message/imap-uid.vala b/src/engine/imap/message/imap-uid.vala
index 049807a..1796e72 100644
--- a/src/engine/imap/message/imap-uid.vala
+++ b/src/engine/imap/message/imap-uid.vala
@@ -32,7 +32,7 @@ public class Geary.Imap.UID : Geary.MessageData.Int64MessageData, Geary.Imap.Mes
     /**
      * Creates a new { link UID} without checking for validity.
      *
-     * @see UID.checked
+     * @see UID.UID.checked
      * @see is_value_valid
      */
     public UID(int64 value) {
diff --git a/src/engine/imap/parameter/imap-list-parameter.vala 
b/src/engine/imap/parameter/imap-list-parameter.vala
index 0f52be9..8ca8e68 100644
--- a/src/engine/imap/parameter/imap-list-parameter.vala
+++ b/src/engine/imap/parameter/imap-list-parameter.vala
@@ -135,7 +135,7 @@ public class Geary.Imap.ListParameter : Geary.Imap.Parameter {
     /**
      * Clears the { link ListParameter} of all its children.
      *
-     * This also clears (sets to null) the parents of all { link ListParamater} children.
+     * This also clears (sets to null) the parents of all ListParameter's children.
      */
     public void clear() {
         // sever ties to ListParameter children
diff --git a/src/engine/imap/parameter/imap-number-parameter.vala 
b/src/engine/imap/parameter/imap-number-parameter.vala
index 614d8ee..5884565 100644
--- a/src/engine/imap/parameter/imap-number-parameter.vala
+++ b/src/engine/imap/parameter/imap-number-parameter.vala
@@ -40,7 +40,7 @@ public class Geary.Imap.NumberParameter : UnquotedStringParameter {
      * Creates a { link NumberParameter} for a string representation of a number.
      *
      * No checking is performed to verify that the string is only composed of numeric characters.
-     * Use { link is_numeric}.
+     * Use { link is_ascii_numeric}.
      */
     public NumberParameter.from_ascii(string ascii) {
         base (ascii);
diff --git a/src/engine/imap/parameter/imap-string-parameter.vala 
b/src/engine/imap/parameter/imap-string-parameter.vala
index bff626e..4be91e7 100644
--- a/src/engine/imap/parameter/imap-string-parameter.vala
+++ b/src/engine/imap/parameter/imap-string-parameter.vala
@@ -26,7 +26,7 @@ public abstract class Geary.Imap.StringParameter : Geary.Imap.Parameter {
     public string ascii { get; private set; }
     
     /**
-     * Returns { link value} or null if value is empty (zero-length).
+     * Returns { link ascii} or null if value is empty (zero-length).
      */
     public string? nullable_ascii {
         get {
@@ -164,9 +164,10 @@ public abstract class Geary.Imap.StringParameter : Geary.Imap.Parameter {
     }
     
     /**
-     * Converts the { link value} to a signed 32-bit integer, clamped between clamp_min and clamp_max.
+     * Converts the { link ascii} to a signed 32-bit integer, clamped between clamp_min and
+     * clamp_max.
      *
-     * ImapError.INVALID is thrown if the { link StringParameter} contains non-numeric values.  No
+     * @throws ImapError.INVALID if the { link StringParameter} contains non-numeric values.  No
      * error is thrown if the numeric value is outside the clamped range.
      */
     public int32 as_int32(int32 clamp_min = int32.MIN, int32 clamp_max = int32.MAX) throws ImapError {
@@ -177,9 +178,10 @@ public abstract class Geary.Imap.StringParameter : Geary.Imap.Parameter {
     }
     
     /**
-     * Converts the { link value} to a signed 64-bit integer, clamped between clamp_min and clamp_max.
+     * Converts the { link ascii} to a signed 64-bit integer, clamped between clamp_min and
+     * clamp_max.
      *
-     * ImapError.INVALID is thrown if the { link StringParameter} contains non-numeric values.  No
+     * @throws ImapError.INVALID if the { link StringParameter} contains non-numeric values.  No
      * error is thrown if the numeric value is outside the clamped range.
      */
     public int64 as_int64(int64 clamp_min = int64.MIN, int64 clamp_max = int64.MAX) throws ImapError {
@@ -194,7 +196,7 @@ public abstract class Geary.Imap.StringParameter : Geary.Imap.Parameter {
      *
      * Returns null if unsuitable for a NumberParameter.
      *
-     * @see NumberParameter.is_ascii_number
+     * @see NumberParameter.is_ascii_numeric
      */
     public NumberParameter? coerce_to_number_parameter() {
         NumberParameter? numberp = this as NumberParameter;
diff --git a/src/engine/imap/response/imap-capabilities.vala b/src/engine/imap/response/imap-capabilities.vala
index 1503c55..8fdf1db 100644
--- a/src/engine/imap/response/imap-capabilities.vala
+++ b/src/engine/imap/response/imap-capabilities.vala
@@ -56,7 +56,7 @@ public class Geary.Imap.Capabilities : Geary.GenericCapabilities {
     }
     
     /**
-     * Indicates the { link ClientSession{ reported support for SPECIAL-USE.
+     * Indicates the { link ClientSession} reported support for SPECIAL-USE.
      *
      * See [[https://tools.ietf.org/html/rfc6154]]
      */
diff --git a/src/engine/imap/response/imap-fetched-data.vala b/src/engine/imap/response/imap-fetched-data.vala
index 54292d4..dd750f5 100644
--- a/src/engine/imap/response/imap-fetched-data.vala
+++ b/src/engine/imap/response/imap-fetched-data.vala
@@ -95,10 +95,10 @@ public class Geary.Imap.FetchedData : Object {
     /**
      * Returns the merge of this { link FetchedData} and the supplied one.
      *
-     * The results are undefined if both FetchData objects contain the same { link FetchDataType}
-     * or { link FetchBodyDataType}s.
+     * The results are undefined if both FetchData objects contain the same
+     * { link FetchDataSpecifier} or { link FetchBodyDataSpecifier}s.
      *
-     * See warnings at { link body_data_map} for dealing with multiple FetchBodyDataTypes.
+     * See warnings at { link body_data_map} for dealing with multiple FetchBodyDataSpecifiers.
      *
      * @return null if the FetchedData do not have the same { link seq_num}.
      */
diff --git a/src/engine/mime/mime-content-disposition.vala b/src/engine/mime/mime-content-disposition.vala
index de7330d..a68fb45 100644
--- a/src/engine/mime/mime-content-disposition.vala
+++ b/src/engine/mime/mime-content-disposition.vala
@@ -47,7 +47,7 @@ public class Geary.Mime.ContentDisposition : Geary.BaseObject {
     public const string SIZE = "size";
     
     /**
-     * The { link DispositionType}, which is { link DispositionType.NONE} if not specified.
+     * The { link DispositionType}, which is { link DispositionType.UNSPECIFIED} if not specified.
      */
     public DispositionType disposition_type { get; private set; }
     
diff --git a/src/engine/mime/mime-content-parameters.vala b/src/engine/mime/mime-content-parameters.vala
index cb79966..28b23f0 100644
--- a/src/engine/mime/mime-content-parameters.vala
+++ b/src/engine/mime/mime-content-parameters.vala
@@ -52,8 +52,8 @@ public class Geary.Mime.ContentParameters : BaseObject {
      * for some parameter values to be case-sensitive and so they are stored as such.  It is up
      * to the caller to use the right comparison method.
      *
-     * @see is_parameter_ci
-     * @see is_parameter_cs
+     * @see has_value_ci
+     * @see has_value_cs
      */
     public Gee.Map<string, string> get_parameters() {
         return params.read_only_view;
@@ -71,7 +71,7 @@ public class Geary.Mime.ContentParameters : BaseObject {
     /**
      * Returns true if the attribute has the supplied value (case-insensitive comparison).
      *
-     * @see has_value_ci
+     * @see has_value_cs
      */
     public bool has_value_ci(string attribute, string value) {
         string? stored = params.get(attribute);
@@ -82,7 +82,7 @@ public class Geary.Mime.ContentParameters : BaseObject {
     /**
      * Returns true if the attribute has the supplied value (case-sensitive comparison).
      *
-     * @see has_value_cs
+     * @see has_value_ci
      */
     public bool has_value_cs(string attribute, string value) {
         string? stored = params.get(attribute);
diff --git a/src/engine/mime/mime-content-type.vala b/src/engine/mime/mime-content-type.vala
index c4dc791..f2339a4 100644
--- a/src/engine/mime/mime-content-type.vala
+++ b/src/engine/mime/mime-content-type.vala
@@ -85,7 +85,7 @@ public class Geary.Mime.ContentType : Geary.BaseObject {
     /**
      * Compares the { link media_type} with the supplied type.
      *
-     * An asterisk ("*") or { link WILDCARD) are accepted, which will always return true.
+     * An asterisk ("*") or { link WILDCARD} are accepted, which will always return true.
      *
      * @see is_type
      */
@@ -96,7 +96,7 @@ public class Geary.Mime.ContentType : Geary.BaseObject {
     /**
      * Compares the { link media_subtype} with the supplied subtype.
      *
-     * An asterisk ("*") or { link WILDCARD) are accepted, which will always return true.
+     * An asterisk ("*") or { link WILDCARD} are accepted, which will always return true.
      *
      * @see is_type
      */
diff --git a/src/engine/nonblocking/nonblocking-variants.vala 
b/src/engine/nonblocking/nonblocking-variants.vala
index acd4eaa..b2f576d 100644
--- a/src/engine/nonblocking/nonblocking-variants.vala
+++ b/src/engine/nonblocking/nonblocking-variants.vala
@@ -5,7 +5,7 @@
  */
 
 /**
- * A Semaphore is a broadcasting, manually-resetting { link AbstractSempahore}.
+ * A Semaphore is a broadcasting, manually-resetting { link AbstractSemaphore}.
  */
 
 public class Geary.Nonblocking.Semaphore : Geary.Nonblocking.AbstractSemaphore {
@@ -15,7 +15,7 @@ public class Geary.Nonblocking.Semaphore : Geary.Nonblocking.AbstractSemaphore {
 }
 
 /**
- * An Event is a broadcasting, auto-resetting { link AbstractSempahore}.
+ * An Event is a broadcasting, auto-resetting { link AbstractSemaphore}.
  */
 
 public class Geary.Nonblocking.Event : Geary.Nonblocking.AbstractSemaphore {
@@ -25,7 +25,7 @@ public class Geary.Nonblocking.Event : Geary.Nonblocking.AbstractSemaphore {
 }
 
 /**
- * A Spinlock is a single-notifying, auto-resetting { link AbstractSempahore}.
+ * A Spinlock is a single-notifying, auto-resetting { link AbstractSemaphore}.
  */
 
 public class Geary.Nonblocking.Spinlock : Geary.Nonblocking.AbstractSemaphore {
diff --git a/src/engine/rfc822/rfc822-mailbox-addresses.vala b/src/engine/rfc822/rfc822-mailbox-addresses.vala
index c70f1ff..2c60aca 100644
--- a/src/engine/rfc822/rfc822-mailbox-addresses.vala
+++ b/src/engine/rfc822/rfc822-mailbox-addresses.vala
@@ -78,7 +78,7 @@ public class Geary.RFC822.MailboxAddresses : Geary.MessageData.AbstractMessageDa
      * Returns the addresses suitable for insertion into an RFC822 message.  RFC822 quoting is
      * performed if required.
      *
-     * @see RFC822.to_rfc822_string
+     * @see MailboxAddress.to_rfc822_string
      */
     public string to_rfc822_string() {
         return MailboxAddress.list_to_string(addrs, "", (a) => a.to_rfc822_string());
diff --git a/src/engine/rfc822/rfc822-message.vala b/src/engine/rfc822/rfc822-message.vala
index 1e1283d..e389348 100644
--- a/src/engine/rfc822/rfc822-message.vala
+++ b/src/engine/rfc822/rfc822-message.vala
@@ -560,7 +560,7 @@ public class Geary.RFC822.Message : BaseObject {
      * See { link get_body} for more details on how the body is assembled from the message's MIME
      * structure and the role of the { link InlinePartReplacer}.
      *
-     * @throws { link RFC822Error.NOT_FOUND} if an HTML body is not present.
+     * @throws RFC822Error.NOT_FOUND if an HTML body is not present.
      */
     public string? get_html_body(InlinePartReplacer? replacer) throws RFC822Error {
         return internal_get_body("html", false, replacer);
diff --git a/src/engine/util/util-synchronization.vala b/src/engine/util/util-synchronization.vala
index 340b087..584a020 100644
--- a/src/engine/util/util-synchronization.vala
+++ b/src/engine/util/util-synchronization.vala
@@ -38,7 +38,7 @@ public class SpinWaiter : BaseObject {
      * Spins waiting for a completion state to be reached.
      *
      * There's two ways the completion state can be reached: (1) PollService returns false,
-     * indicating an abort state, (2) { link stop} is called, indicating a success state, or
+     * indicating an abort state, (2) { link notify} is called, indicating a success state, or
      * (3) the Cancellable was cancelled, causing an IOError.CANCELLED exception to be thrown.
      *
      * { link PollService} will be called from within the calling thread context.
@@ -46,8 +46,6 @@ public class SpinWaiter : BaseObject {
      * Although this is thread-safe, it's not designed to be invoked by multiple callers.  That
      * could cause the PollService callback to be called more often than specified in the
      * constructor.
-     *
-     * @see stop
      */
     public bool wait(Cancellable? cancellable = null) throws Error {
         // normalize poll_msec; negative values are zeroed
@@ -86,12 +84,10 @@ public class SpinWaiter : BaseObject {
     }
     
     /**
-     * Signals a completion state to a thread calling { link spin}.
+     * Signals a completion state to a thread calling { link wait}.
      *
      * This call is thread-safe.  However, once a { link SpinWaiter} has been signalled to stop,
      * it cannot be restarted.
-     *
-     * @see spin
      */
     public new void notify() {
         mutex.lock();
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]