Sufficient valadoc

src/Application.vala

@@ -3,20 +3,32 @@
  * SPDX-FileCopyrightText: 2021-2024 Ryo Nakano <[email protected]>
  */
 
+/**
+ * The foundation class to manage the app and its window.
+ */
 public class Application : Adw.Application {
+    /**
+     * Action names and their callbacks.
+     */
     private const ActionEntry[] ACTION_ENTRIES = {
         { "quit", on_quit_activate },
     };
 
+    /**
+     * The instance of the application settings.
+     */
     public static Settings settings { get; private set; }
 
     /**
      * The language name that the user prefers in the system settings, e.g. "en_US", "ja_JP", etc.
      *
-     * Used to show the KEY_NAME and KEY_COMMENT in the user's system language.
+     * Used to show the ``KEY_NAME`` and ``KEY_COMMENT`` in the user's system language.
      */
     public static unowned string preferred_language { get; private set; }
 
+    /**
+     * The instance of the app window.
+     */
     private MainWindow main_window;
 
     public Application () {
@@ -34,6 +46,16 @@ public class Application : Adw.Application {
         preferred_language = languages[0];
     }
 
+    /**
+     * Convert ``from_value`` to ``to_value``.
+     *
+     * @param binding a binding
+     * @param from_value the value of Action.state property
+     * @param to_value the value of Adw.StyleManager.color_scheme property
+     * @return true if the transformation was successful, false otherwise
+     *
+     * @see GLib.BindingTransformFunc
+     */
     private bool style_action_transform_to_cb (Binding binding, Value from_value, ref Value to_value) {
         Variant? variant = from_value.dup_variant ();
         if (variant == null) {
@@ -56,6 +78,16 @@ public class Application : Adw.Application {
         return true;
     }
 
+    /**
+     * Convert ``from_value`` to ``to_value``.
+     *
+     * @param binding a binding
+     * @param from_value the value of Adw.StyleManager.color_scheme property
+     * @param to_value the value of Action.state property
+     * @return true if the transformation was successful, false otherwise
+     *
+     * @see GLib.BindingTransformFunc
+     */
     private bool style_action_transform_from_cb (Binding binding, Value from_value, ref Value to_value) {
         var val = (Adw.ColorScheme) from_value;
         switch (val) {
@@ -72,18 +104,27 @@ public class Application : Adw.Application {
         return true;
     }
 
-    private static bool color_scheme_get_mapping_cb (Value value, Variant variant, void* user_data) {
-        // Convert from the "style" enum defined in the gschema to Adw.ColorScheme
-        var val = variant.get_string ();
+    /**
+     * Convert from the "style" enum defined in the gschema to Adw.ColorScheme.
+     *
+     * @param to_value return location for the "color-scheme" property value of ``style_manager``
+     * @param from_variant the Variant containing "style" enum value of {@link settings}
+     * @param user_data unused (null)
+     * @return true if the conversion succeeded, false otherwise
+     *
+     * @see GLib.SettingsBindGetMappingShared
+     */
+    private static bool color_scheme_get_mapping_cb (Value to_value, Variant from_variant, void* user_data) {
+        var val = from_variant.get_string ();
         switch (val) {
             case Define.Style.DEFAULT:
-                value.set_enum (Adw.ColorScheme.DEFAULT);
+                to_value.set_enum (Adw.ColorScheme.DEFAULT);
                 break;
             case Define.Style.LIGHT:
-                value.set_enum (Adw.ColorScheme.FORCE_LIGHT);
+                to_value.set_enum (Adw.ColorScheme.FORCE_LIGHT);
                 break;
             case Define.Style.DARK:
-                value.set_enum (Adw.ColorScheme.FORCE_DARK);
+                to_value.set_enum (Adw.ColorScheme.FORCE_DARK);
                 break;
             default:
                 warning ("color_scheme_get_mapping_cb: Invalid style: %s", val);
@@ -93,11 +134,20 @@ public class Application : Adw.Application {
         return true;
     }
 
-    private static Variant color_scheme_set_mapping_cb (Value value, VariantType expected_type, void* user_data) {
+    /**
+     * Convert from Adw.ColorScheme to the "style" enum defined in the gschema.
+     *
+     * @param from_value the "color-scheme" property value of ``style_manager``
+     * @param expected_type the expected type of Variant that this method returns
+     * @param user_data unused (null)
+     * @return a new Variant holding the data from ``from_value``
+     *
+     * @see GLib.SettingsBindSetMappingShared
+     */
+    private static Variant color_scheme_set_mapping_cb (Value from_value, VariantType expected_type, void* user_data) {
         string color_scheme;
 
-        // Convert from Adw.ColorScheme to the "style" enum defined in the gschema
-        var val = (Adw.ColorScheme) value;
+        var val = (Adw.ColorScheme) from_value;
         switch (val) {
             case Adw.ColorScheme.DEFAULT:
                 color_scheme = Define.Style.DEFAULT;
@@ -118,6 +168,13 @@ public class Application : Adw.Application {
         return new Variant.string (color_scheme);
     }
 
+    /**
+     * Make it possible to change the app style with the following action names
+     * and remember that preference to {@link settings}.
+     *
+     * You can change the app style by passsing Adw.ColorScheme value as a target value
+     * to the ``app.color-scheme`` action.
+     */
     private void setup_style () {
         var style_action = new SimpleAction.stateful (
             "color-scheme", VariantType.INT32, new Variant.int32 (Adw.ColorScheme.DEFAULT)
@@ -133,13 +190,14 @@ public class Application : Adw.Application {
         add_action (style_action);
     }
 
+    /**
+     * Setup localization, app style, and accel keys.
+     */
     protected override void startup () {
         base.startup ();
 
-        /*
-         * Make sure the app is shown in the user's language.
-         * https://docs.gtk.org/glib/i18n.html#internationalization
-         */
+        // Make sure the app is shown in the user's language.
+        // https://docs.gtk.org/glib/i18n.html#internationalization
         Intl.setlocale (LocaleCategory.ALL, "");
         Intl.bindtextdomain (Config.PROJECT_NAME, Config.LOCALEDIR);
         Intl.bind_textdomain_codeset (Config.PROJECT_NAME, "UTF-8");
@@ -152,6 +210,12 @@ public class Application : Adw.Application {
         set_accels_for_action ("win.new", { "<Control>n" });
     }
 
+    /**
+     * Show {@link MainWindow}.
+     *
+     * If there is an instance of {@link MainWindow}, show it and leave the method.<<BR>>
+     * Otherwise, initialize it, show it, and binding window sizes/states.
+     */
     protected override void activate () {
         if (main_window != null) {
             main_window.present ();
@@ -166,10 +230,8 @@ public class Application : Adw.Application {
         settings.bind ("window-height", main_window, "default-height", SettingsBindFlags.DEFAULT);
         settings.bind ("window-width", main_window, "default-width", SettingsBindFlags.DEFAULT);
 
-        /*
-         * Binding of window maximization with "SettingsBindFlags.DEFAULT" results the window getting bigger and bigger on open.
-         * So we use the prepared binding only for setting
-         */
+        // Binding of window maximization with "SettingsBindFlags.DEFAULT" results the window getting bigger and bigger on open.
+        // So we use the prepared binding only for setting
         bool is_maximized = Application.settings.get_boolean ("window-maximized");
         if (is_maximized) {
             main_window.maximize ();
@@ -178,6 +240,11 @@ public class Application : Adw.Application {
         settings.bind ("window-maximized", main_window, "maximized", SettingsBindFlags.SET);
     }
 
+    /**
+     * The callback for "app.quit" action.
+     *
+     * Perform pre-destruction process if there is an instance of {@link MainWindow}, otherwise quit the app immediately.
+     */
     private void on_quit_activate () {
         if (main_window != null) {
             main_window.prep_destroy ();

src/Define.vala

@@ -3,37 +3,46 @@
  * SPDX-FileCopyrightText: 2021-2024 Ryo Nakano <[email protected]>
  */
 
+/**
+ * Defines constants used in the project widely.
+ */
 namespace Define {
     /**
      * The name of the application.
      *
-     * Use this to prevent the app name from being translated.
+     * Use this constant to prevent the app name from being translated.
      */
     public const string APP_NAME = "Pin It!";
 
     /**
-     * A key under g_key_file_desktop_group, whose value is a list of strings giving the keywords which may be used in
+     * A key under ``g_key_file_desktop_group``, whose value is a list of strings giving the keywords which may be used in
      * addition to other metadata to describe this entry.
      *
-     * Using KeyFileDesktop.KEY_KEYWORDS will cause the cc failing with "‘G_KEY_FILE_DESKTOP_KEY_KEYWORDS’ undeclared"
-     * error. This constant does not seem to be defined in the original glib and defined in the following patch.
-     * (and maybe valac uses glibc with this patch and thus it does not complain any error.)
-     *
-     * [[https://sources.debian.org/patches/glib2.0/2.78.3-2/01_gettext-desktopfiles.patch/]]
-     *
-     * I just keep to borrow the definition of KEY_KEYWORDS here instead of applying the patch,
+     * Note: Using ``KeyFileDesktop.KEY_KEYWORDS`` will cause the cc failing with ``‘G_KEY_FILE_DESKTOP_KEY_KEYWORDS’ undeclared``
+     * error.<<BR>>
+     * This constant does not seem to be defined in the original glib and defined in the following patch.<<BR>>
+     * (and maybe valac uses glibc with this patch and thus it does not complain any error.)<<BR>>
+     * <<BR>>
+     * [[https://sources.debian.org/patches/glib2.0/2.78.3-2/01_gettext-desktopfiles.patch/]]<<BR>>
+     * <<BR>>
+     * We just keep to borrow the definition of KEY_KEYWORDS here instead of applying the patch,
      * since it might have side effect.
      */
     public const string KEY_KEYWORDS = "Keywords";
 
     /**
-     * Defines response IDs used in Adw.MessageDialog.
+     * Response IDs used in Adw.MessageDialog.
      */
     namespace DialogResponse {
+        /** Use this constant instead of the literal string ``close``. */
         public const string CLOSE = "close";
+        /** Use this constant instead of the literal string ``cancel``. */
         public const string CANCEL = "cancel";
+        /** Use this constant instead of the literal string ``ok``. */
         public const string OK = "ok";
+        /** Use this constant instead of the literal string ``discard``. */
         public const string DISCARD = "discard";
+        /** Use this constant instead of the literal string ``save``. */
         public const string SAVE = "save";
     }
 

src/MainWindow.vala

@@ -3,6 +3,23 @@
  * SPDX-FileCopyrightText: 2021-2024 Ryo Nakano <[email protected]>
  */
 
+/**
+ * The window of the application.
+ *
+ * It contains a ``Adw.NavigationSplitView`` as a view which has a {@link View.FilesView} and
+ * {@link View.EditView} inside.
+ *
+ * It also has a instance of {@link Model.DesktopFileModel} and calls {@link Model.DesktopFileModel.load} when:
+ *
+ *  * constructed
+ *  * {@link View.FilesView.deleted} is emitted
+ *  * {@link View.EditView.saved} is emitted
+ *  * the action ``win.new`` is called
+ *
+ * If {@link Model.DesktopFileModel.load} succeeded, this calls {@link View.FilesView.set_list_data} to reflect
+ * load result.<<BR>>
+ * Otherwise, this shows a dialog to tell the user about the failure.
+ */
 public class MainWindow : Adw.ApplicationWindow {
     private const ActionEntry[] ACTION_ENTRIES = {
         { "about", on_about_activate },
@@ -99,7 +116,7 @@ public class MainWindow : Adw.ApplicationWindow {
     /**
      * The callback when loading the list of desktop files failed.
      *
-     * Tell the user the failure through the dialog.
+     * Tell the user the failure through a dialog.
      */
     private void on_load_failure () {
         var error_dialog = new Adw.MessageDialog (this,
@@ -123,7 +140,7 @@ public class MainWindow : Adw.ApplicationWindow {
      * Preprocess before destruction of this.
      *
      * Just destroy this if we never edited entries or no changes made for desktop files.
-     * Otherwise, tell the user unsaved work through dialog.
+     * Otherwise, tell the user unsaved work through a dialog.
      */
     public void prep_destroy () {
         // Never edited entries
@@ -172,9 +189,12 @@ public class MainWindow : Adw.ApplicationWindow {
     }
 
     /**
-     * Start editing the given DesktopFile
+     * Start editing the given {@link Model.DesktopFile}.
+     *
+     * It first backups the given {@link Model.DesktopFile} and then calls {@link View.EditView.load_file} to start
+     * editing, so that the app can recognize unsaved changes before destruction.
      *
-     * @param file The DesktopFile to edit.
+     * @param file The {@link Model.DesktopFile} to edit
      */
     public void show_edit_view (Model.DesktopFile file) {
         desktop_file = file;
@@ -210,12 +230,12 @@ public class MainWindow : Adw.ApplicationWindow {
      * The callback for about window.
      */
     private void on_about_activate () {
-        // List code contributors
+        // List of code contributors
         const string[] DEVELOPERS = {
             "Ryo Nakano https://github.com/ryonakano",
             "Jeyson Flores https://github.com/JeysonFlores",
         };
-        // List icon authors
+        // List of icon authors
         const string[] ARTISTS = {
             "hanaral https://github.com/hanaral",
         };
@@ -235,7 +255,10 @@ public class MainWindow : Adw.ApplicationWindow {
             developer_name = "Ryo Nakano",
             developers = DEVELOPERS,
             artists = ARTISTS,
-            ///TRANSLATORS: Replace with your name; don't translate literally
+            ///TRANSLATORS: A newline-separated list of translators. Don't translate literally.
+            ///You may add your name and your email address/website URL if you want, e.g.:
+            ///John Doe <[email protected]>
+            ///Jane Doe <https://example.com>
             translator_credits = _("translator-credits")
         };