[geary/mjog/enable-client-valadoc: 2/2] src/client: Fix warnings and errors reported by valadoc

From: Michael Gratton <mjog src gnome org>
To: commits-list gnome org
Cc:
Subject: [geary/mjog/enable-client-valadoc: 2/2] src/client: Fix warnings and errors reported by valadoc
Date: Wed, 8 Apr 2020 02:03:21 +0000 (UTC)
commit 6c935b500c5c18d1a5fc2fca71e0b78ccff913a6
Author: Michael Gratton <mike vee net>
Date:   Wed Apr 8 12:01:10 2020 +1000

    src/client: Fix warnings and errors reported by valadoc

 src/client/accounts/accounts-editor-row.vala          |  5 +++--
 src/client/accounts/accounts-editor.vala              |  4 ++--
 src/client/application/application-configuration.vala |  2 +-
 src/client/application/application-controller.vala    |  4 ++--
 src/client/composer/composer-box.vala                 |  2 +-
 src/client/composer/composer-embed.vala               |  4 ++--
 src/client/composer/composer-link-popover.vala        |  8 ++++----
 src/client/composer/composer-widget.vala              | 11 ++++++-----
 src/client/composer/composer-window.vala              |  2 +-
 src/client/plugin/plugin-application.vala             | 13 ++++++-------
 src/client/plugin/plugin-contact-store.vala           |  2 +-
 src/client/plugin/plugin-email-extension.vala         | 16 ++++++++--------
 src/client/plugin/plugin-email-store.vala             |  7 ++++---
 src/client/plugin/plugin-folder-extension.vala        | 16 ++++++++--------
 src/client/plugin/plugin-folder-store.vala            |  7 ++++---
 src/client/plugin/plugin-folder.vala                  |  2 +-
 src/client/plugin/plugin-notification-extension.vala  |  4 ++--
 src/client/util/util-email.vala                       |  5 +++--
 18 files changed, 59 insertions(+), 55 deletions(-)
---
diff --git a/src/client/accounts/accounts-editor-row.vala b/src/client/accounts/accounts-editor-row.vala
index bbe9218d..1e6ef2a2 100644
--- a/src/client/accounts/accounts-editor-row.vala
+++ b/src/client/accounts/accounts-editor-row.vala
@@ -417,7 +417,8 @@ internal interface Accounts.ValidatingRow : EditorRow {
      *
      * This is only called when the row's value has changed, is
      * valid, and the user has activated or changed to a different
-     * row. */
+     * row.
+     */
     protected virtual void commit() {
         // noop
     }
@@ -590,7 +591,7 @@ internal class Accounts.EditorPopover : Gtk.Popover {
         this.closed.disconnect(on_closed);
     }
 
-    /** {@inheritdoc} */
+    /** {@inheritDoc} */
     public new void popup() {
         // Work-around GTK+ issue #1138
         Gtk.Widget target = get_relative_to();
diff --git a/src/client/accounts/accounts-editor.vala b/src/client/accounts/accounts-editor.vala
index 4f14e88f..3e5a8887 100644
--- a/src/client/accounts/accounts-editor.vala
+++ b/src/client/accounts/accounts-editor.vala
@@ -186,8 +186,8 @@ public class Accounts.Editor : Gtk.Dialog {
      * Prompts for pinning a certificate using the certificate manager.
      *
      * This provides a thing wrapper around {@link
-     * CertificateManager.prompt_pin_certificate} that uses the
-     * account editor as the dialog parent.
+     * Application.CertificateManager.prompt_pin_certificate} that
+     * uses the account editor as the dialog parent.
      */
     internal async void prompt_pin_certificate(Geary.AccountInformation account,
                                                Geary.ServiceInformation service,
diff --git a/src/client/application/application-configuration.vala 
b/src/client/application/application-configuration.vala
index b089306f..00c359c9 100644
--- a/src/client/application/application-configuration.vala
+++ b/src/client/application/application-configuration.vala
@@ -226,7 +226,7 @@ public class Application.Configuration : Geary.BaseObject {
      * client. By default, the set will contain languages based on
      * environment variables.
      *
-     * @see Util.International.get_user_preferred_languages
+     * @see Util.I18n.get_user_preferred_languages
      */
     public string[] get_spell_check_languages() {
         GLib.Variant? value = this.settings.get_value(
diff --git a/src/client/application/application-controller.vala 
b/src/client/application/application-controller.vala
index f680a409..da52ef18 100644
--- a/src/client/application/application-controller.vala
+++ b/src/client/application/application-controller.vala
@@ -10,8 +10,8 @@
 /**
  * Primary controller for an application instance.
  *
- * A single instance of this class is constructed by {@link
- * GearyAplication} when the primary application instance is started.
+ * A single instance of this class is constructed by {@link Client}
+ * when the primary application instance is started.
  */
 internal class Application.Controller : Geary.BaseObject {
 
diff --git a/src/client/composer/composer-box.vala b/src/client/composer/composer-box.vala
index 971f0fae..1ea515ce 100644
--- a/src/client/composer/composer-box.vala
+++ b/src/client/composer/composer-box.vala
@@ -10,7 +10,7 @@
  * A container for full-height paned composers in the main window.
  *
  * Adding a composer to this container places it in {@link
- * PresentationMode.PANED} mode.
+ * Widget.PresentationMode.PANED} mode.
  */
 public class Composer.Box : Gtk.Frame, Container {
 
diff --git a/src/client/composer/composer-embed.vala b/src/client/composer/composer-embed.vala
index e124dc95..d92aca6d 100644
--- a/src/client/composer/composer-embed.vala
+++ b/src/client/composer/composer-embed.vala
@@ -10,8 +10,8 @@
  * A container for full-height paned composers in the main window.
  *
  * Adding a composer to this container places it in {@link
- * PresentationMode.INLINE} or {@link PresentationMode.INLINE_COMPACT}
- * mode.
+ * Widget.PresentationMode.INLINE} or {@link
+ * Widget.PresentationMode.INLINE_COMPACT} mode.
  */
 public class Composer.Embed : Gtk.EventBox, Container {
 
diff --git a/src/client/composer/composer-link-popover.vala b/src/client/composer/composer-link-popover.vala
index b88cf976..489a8984 100644
--- a/src/client/composer/composer-link-popover.vala
+++ b/src/client/composer/composer-link-popover.vala
@@ -12,10 +12,10 @@
  * The exact appearance of the popover will depend on the {@link
  * Type} passed to the constructor:
  *
- * - For {@link Type.NEW_LINK}, the user will be presented with an
- *   insert button and an open button.
- * - For {@link Type.EXISTING_LINK}, the user will be presented with
- *   an update, delete and open buttons.
+ *  * For {@link Type.NEW_LINK}, the user will be presented with an
+ *    insert button and an open button.
+ *  * For {@link Type.EXISTING_LINK}, the user will be presented with
+ *    an update, delete and open buttons.
  */
 [GtkTemplate (ui = "/org/gnome/Geary/composer-link-popover.ui")]
 public class Composer.LinkPopover : Gtk.Popover {
diff --git a/src/client/composer/composer-widget.vala b/src/client/composer/composer-widget.vala
index cacb810b..6cceec72 100644
--- a/src/client/composer/composer-widget.vala
+++ b/src/client/composer/composer-widget.vala
@@ -17,7 +17,8 @@ private extern Type components_reflow_box_get_type();
 /**
  * A widget for editing an email message.
  *
- * Composers must always be placed in an instance of {@link ComposerContainer}.
+ * Composers must always be placed in an instance of {@link
+ * Container}.
  */
 [GtkTemplate (ui = "/org/gnome/Geary/composer-widget.ui")]
 public class Composer.Widget : Gtk.EventBox, Geary.BaseInterface {
@@ -806,10 +807,10 @@ public class Composer.Widget : Gtk.EventBox, Geary.BaseInterface {
     /**
      * Prompts to close the composer if needed, before closing it.
      *
-     * If the composer is already closed no action is taken.  If the
-     * composer is blank then this method will call {@link exit},
-     * destroying the composer, else the composer will either be saved
-     * or discarded as needed then closed.
+     * If the composer is already closed no action is taken. If the
+     * composer is blank then this method will close the composer,
+     * else the composer will either be saved or discarded as needed
+     * then closed.
      *
      * The return value specifies whether the composer is being closed
      * or if the prompt was cancelled by a human.
diff --git a/src/client/composer/composer-window.vala b/src/client/composer/composer-window.vala
index a1488b44..c3d1db7b 100644
--- a/src/client/composer/composer-window.vala
+++ b/src/client/composer/composer-window.vala
@@ -10,7 +10,7 @@
  * A container detached composers, i.e. in their own separate window.
  *
  * Adding a composer to this container places it in {@link
- * PresentationMode.DETACHED} mode.
+ * Widget.PresentationMode.DETACHED} mode.
  */
 public class Composer.Window : Gtk.ApplicationWindow, Container {
 
diff --git a/src/client/plugin/plugin-application.vala b/src/client/plugin/plugin-application.vala
index 585f2b7a..af49e5eb 100644
--- a/src/client/plugin/plugin-application.vala
+++ b/src/client/plugin/plugin-application.vala
@@ -8,9 +8,8 @@
 /**
  * An object representing the client application for use by plugins.
  *
- * Plugins may obtain instances of this object from their context
- * objects, for example {@link
- * Application.NotificationContext.get_application}.
+ * Plugins may obtain instances of this object from the {@link
+ * PluginBase.plugin_application} property.
  */
 public interface Plugin.Application : Geary.BaseObject {
 
@@ -19,9 +18,9 @@ public interface Plugin.Application : Geary.BaseObject {
      * Registers a plugin action with the application.
      *
      * Once registered, the action will be available for use in user
-     * interface elements such as {@see Button}.
+     * interface elements such as {@link Button}.
      *
-     * @see unregister_action
+     * @see deregister_action
      */
     public abstract void register_action(GLib.Action action);
 
@@ -47,8 +46,8 @@ public interface Plugin.Application : Geary.BaseObject {
      * the folder, however it may take additional time for the changes
      * to be fully committed and reflected on the remote server.
      *
-     * @throws Error.PERMISSIONS if permission was not granted to
-     * empty the folder
+     * @throws Error.PERMISSION_DENIED if permission to access the
+     * resource was not given
      */
     public abstract async void empty_folder(Folder folder)
         throws Error.PERMISSION_DENIED;
diff --git a/src/client/plugin/plugin-contact-store.vala b/src/client/plugin/plugin-contact-store.vala
index 395cbabb..f85d5087 100644
--- a/src/client/plugin/plugin-contact-store.vala
+++ b/src/client/plugin/plugin-contact-store.vala
@@ -10,7 +10,7 @@
  *
  * Plugins may obtain instances of this object from their context
  * objects, for example {@link
- * Application.NotificationContext.get_contacts_for_folder}.
+ * NotificationContext.get_contacts_for_folder}.
  */
 public interface Plugin.ContactStore : Geary.BaseObject {
 
diff --git a/src/client/plugin/plugin-email-extension.vala b/src/client/plugin/plugin-email-extension.vala
index c439296a..0928bedd 100644
--- a/src/client/plugin/plugin-email-extension.vala
+++ b/src/client/plugin/plugin-email-extension.vala
@@ -44,8 +44,8 @@ public interface Plugin.EmailContext : Geary.BaseObject {
      *
      * This method may prompt for permission before returning.
      *
-     * @throws Error.PERMISSIONS if permission to access
-     * this resource was not given
+     * @throws Error.PERMISSION_DENIED if permission to access the
+     * resource was not given
      */
     public abstract async EmailStore get_email_store()
         throws Error.PERMISSION_DENIED;
@@ -55,12 +55,12 @@ public interface Plugin.EmailContext : Geary.BaseObject {
      *
      * The info bar will be shown for the given email if it is
      * currently displayed in any main window, which can be determined
-     * by connecting to the {@link email_displayed} signal. Further,
-     * if multiple info bars are added for the same email, only the
-     * one with a higher priority will be shown. If that is closed or
-     * removed, the second highest will be shown, and so on. Once the
-     * email is no longer shown, the info bars will be automatically
-     * removed.
+     * by connecting to the {@link EmailStore.email_displayed}
+     * signal. Further, if multiple info bars are added for the same
+     * email, only the one with a higher priority will be shown. If
+     * that is closed or removed, the second highest will be shown,
+     * and so on. Once the email is no longer shown, the info bars
+     * will be automatically removed.
      */
     public abstract void add_email_info_bar(EmailIdentifier displayed,
                                             InfoBar info_bar,
diff --git a/src/client/plugin/plugin-email-store.vala b/src/client/plugin/plugin-email-store.vala
index d36eada8..4f3dcef6 100644
--- a/src/client/plugin/plugin-email-store.vala
+++ b/src/client/plugin/plugin-email-store.vala
@@ -8,9 +8,10 @@
 /**
  * Provides plugins with access to email.
  *
- * Plugins may obtain instances of this object from their context
- * objects, for example {@link
- * Application.NotificationContext.get_email}.
+ * Plugins that implement the {@link EmailExtension} interface may
+ * obtain instances of this object by calling {@link
+ * EmailContext.get_email_store} on their {@link EmailExtension.email}
+ * property.
  */
 public interface Plugin.EmailStore : Geary.BaseObject {
 
diff --git a/src/client/plugin/plugin-folder-extension.vala b/src/client/plugin/plugin-folder-extension.vala
index 37b19d04..c90f0283 100644
--- a/src/client/plugin/plugin-folder-extension.vala
+++ b/src/client/plugin/plugin-folder-extension.vala
@@ -44,8 +44,8 @@ public interface Plugin.FolderContext : Geary.BaseObject {
      *
      * This method may prompt for permission before returning.
      *
-     * @throws Error.PERMISSIONS if permission to access
-     * this resource was not given
+     * @throws Error.PERMISSION_DENIED if permission to access the
+     * resource was not given
      */
     public abstract async FolderStore get_folder_store()
         throws Error.PERMISSION_DENIED;
@@ -55,12 +55,12 @@ public interface Plugin.FolderContext : Geary.BaseObject {
      *
      * The info bar will be shown for the given folder if it is
      * currently selected in any main window, which can be determined
-     * by connecting to the {@link folder_selected} signal. Further,
-     * if multiple info bars are added for the same folder, only the
-     * one with a higher priority will be shown. If that is closed or
-     * removed, the second highest will be shown, and so on. Once the
-     * selected folder changes, the info bars will be automatically
-     * removed.
+     * by connecting to the {@link FolderStore.folder_selected}
+     * signal. Further, if multiple info bars are added for the same
+     * folder, only the one with a higher priority will be shown. If
+     * that is closed or removed, the second highest will be shown,
+     * and so on. Once the selected folder changes, the info bars will
+     * be automatically removed.
      */
     public abstract void add_folder_info_bar(Folder selected,
                                              InfoBar infobar,
diff --git a/src/client/plugin/plugin-folder-store.vala b/src/client/plugin/plugin-folder-store.vala
index 08a05c5f..ec1271f8 100644
--- a/src/client/plugin/plugin-folder-store.vala
+++ b/src/client/plugin/plugin-folder-store.vala
@@ -8,9 +8,10 @@
 /**
  * Provides plugins with access to folders.
  *
- * Plugins may obtain instances of this object from their context
- * objects, for example {@link
- * Application.NotificationContext.get_folder_store}.
+ * Plugins that implement the {@link FolderExtension} interface may
+ * obtain instances of this object by calling {@link
+ * FolderContext.get_folder_store} on their {@link
+ * FolderExtension.folders} property.
  */
 public interface Plugin.FolderStore : Geary.BaseObject {
 
diff --git a/src/client/plugin/plugin-folder.vala b/src/client/plugin/plugin-folder.vala
index 0bbf30a4..bfa43d9e 100644
--- a/src/client/plugin/plugin-folder.vala
+++ b/src/client/plugin/plugin-folder.vala
@@ -37,7 +37,7 @@ public interface Plugin.Folder : Geary.BaseObject {
      * application action parameter.
      *
      * @see FolderStore.get_folder_from_variant
-     * @see folder_variant_type
+     * @see FolderStore.folder_variant_type
      */
     public abstract GLib.Variant to_variant();
 
diff --git a/src/client/plugin/plugin-notification-extension.vala 
b/src/client/plugin/plugin-notification-extension.vala
index d69c4d11..200098c8 100644
--- a/src/client/plugin/plugin-notification-extension.vala
+++ b/src/client/plugin/plugin-notification-extension.vala
@@ -83,8 +83,8 @@ public interface Plugin.NotificationContext : Geary.BaseObject {
      *
      * @throws Error.NOT_FOUND if the given account does
      * not exist
-     * @throws Error.PERMISSIONS if permission to access
-     * this resource was not given
+     * @throws Error.PERMISSION_DENIED if permission to access the
+     * resource was not given
      */
     public abstract async Plugin.ContactStore get_contacts_for_folder(Plugin.Folder source)
         throws Error.NOT_FOUND, Error.PERMISSION_DENIED;
diff --git a/src/client/util/util-email.vala b/src/client/util/util-email.vala
index 173c6a64..7a23919d 100644
--- a/src/client/util/util-email.vala
+++ b/src/client/util/util-email.vala
@@ -104,8 +104,9 @@ namespace Util.Email {
      * is little room for the display.
      *
      * @return a string containing at least the first mailbox
-     * serialised by {@link MailboxAddress.to_short_display}, if the
-     * list contains more mailboxes then an indication of how many
+     * serialised by {@link
+     * Geary.RFC822.MailboxAddress.to_short_display}, if the list
+     * contains more mailboxes then an indication of how many
      * additional are present.
      */
     public string to_short_recipient_display(Geary.EmailHeaderSet headers) {
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]