docs: notifd doc comments

9 files changed, 125 insertions, 97 deletions

diff --git a/docs/default.nix b/docs/default.nix
index 5a85fc3..1f67db8 100644
--- a/docs/default.nix
+++ b/docs/default.nix
@@ -7,6 +7,10 @@
 
   toTOML = (pkgs.formats.toml {}).generate;
 
+  docgen = pkgs.gi-docgen.overrideAttrs {
+    patches = [../nix/doc/gi-docgen.patch];
+  };
+
   genLib = {
     flakepkg,
     gir,
@@ -16,6 +20,8 @@
     authors ? "Aylur",
     dependencies ? {},
     out ? "libastal/${flakepkg}",
+    browse ? flakepkg,
+    website ? flakepkg,
   }: let
     name = "Astal${gir}-${api-ver}";
     src = self.packages.${pkgs.system}.${flakepkg}.dev;
@@ -25,9 +31,9 @@
         inherit description authors;
         version = readVer version;
         license = "LGPL-2.1";
-        browse_url = "https://github.com/aylur/astal";
+        browse_url = "https://github.com/Aylur/astal/tree/main/lib/${browse}";
         repository_url = "https://github.com/aylur/aylur.git";
-        website_url = "https://aylur.github.io/astal";
+        website_url = "https://aylur.github.io/astal/guide/libraries/${website}";
         dependencies = ["GObject-2.0"] ++ (builtins.attrNames dependencies);
       };
 
@@ -90,7 +96,7 @@ in
     src = ./.;
 
     nativeBuildInputs = with pkgs; [
-      gi-docgen
+      docgen
       glib
       json-glib
       gobject-introspection
diff --git a/flake.lock b/flake.lock
index e6e6355..eec56ea 100644
--- a/flake.lock
+++ b/flake.lock
@@ -2,11 +2,11 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1716293225,
-        "narHash": "sha256-pU9ViBVE3XYb70xZx+jK6SEVphvt7xMTbm6yDIF4xPs=",
+        "lastModified": 1729256560,
+        "narHash": "sha256-/uilDXvCIEs3C9l73JTACm4quuHUsIHcns1c+cHUJwA=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "3eaeaeb6b1e08a016380c279f8846e0bd8808916",
+        "rev": "4c2fcb090b1f3e5b47eaa7bd33913b574a11e0a0",
         "type": "github"
       },
       "original": {
diff --git a/flake.nix b/flake.nix
index 1b94c1c..7f644bd 100644
--- a/flake.nix
+++ b/flake.nix
@@ -1,6 +1,4 @@
 {
-  inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
-
   outputs = {
     self,
     nixpkgs,
@@ -22,11 +20,15 @@
           vala
           wayland
           wayland-scanner
+          python3
         ];
         propagatedBuildInputs = [pkgs.glib] ++ inputs;
         pname = name;
         version = readVer "${src}/version";
         src = src;
+        postUnpack = ''
+          cp --remove-destination ${./lib/gir.py} $sourceRoot/gir.py
+        '';
         outputs = ["out" "dev"];
       };
   in {
@@ -59,6 +61,7 @@
       river = mkPkg "astal-river" ./lib/river [json-glib];
       tray = mkPkg "astal-tray" ./lib/tray [gtk3 gdk-pixbuf libdbusmenu-gtk3 json-glib];
       wireplumber = mkPkg "astal-wireplumber" ./lib/wireplumber [wireplumber];
+      # polkit = mkPkg "astal-polkit" ./lib/polkit [polkit];
 
       gjs = pkgs.stdenvNoCC.mkDerivation {
         src = ./lang/gjs;
@@ -73,4 +76,8 @@
       };
     };
   };
+
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+  };
 }
diff --git a/lib/gir.py b/lib/gir.py
new file mode 100644
index 0000000..8ec786f
--- /dev/null
+++ b/lib/gir.py
@@ -0,0 +1,43 @@
+"""
+Vala's generated gir does not contain comments,
+so we use valadoc to generate them. However, they are formatted
+for valadoc and not gi-docgen so we need to fix it.
+"""
+
+import xml.etree.ElementTree as ET
+import html
+import sys
+import subprocess
+
+
+def fix_gir(gir: str):
+    namespaces = {
+        "": "http://www.gtk.org/introspection/core/1.0",
+        "c": "http://www.gtk.org/introspection/c/1.0",
+        "glib": "http://www.gtk.org/introspection/glib/1.0",
+    }
+    for prefix, uri in namespaces.items():
+        ET.register_namespace(prefix, uri)
+
+    tree = ET.parse(gir)
+    root = tree.getroot()
+
+    for doc in root.findall(".//doc", namespaces):
+        if doc.text:
+            doc.text = (
+                html.unescape(doc.text).replace("<para>", "").replace("</para>", "")
+            )
+
+    tree.write(gir, encoding="utf-8", xml_declaration=True)
+
+
+def valadoc(gir: str, args: list[str]):
+    subprocess.run(["valadoc", "-o", "docs", "--gir", gir, *args])
+
+
+if __name__ == "__main__":
+    gir = sys.argv[1]
+    args = sys.argv[2:]
+
+    valadoc(gir, args)
+    fix_gir(gir)
diff --git a/lib/notifd/gir.py b/lib/notifd/gir.py
new file mode 120000
index 0000000..b5b4f1d
--- /dev/null
+++ b/lib/notifd/gir.py
@@ -0,0 +1 @@
+../gir.py
\ No newline at end of file
diff --git a/lib/notifd/meson.build b/lib/notifd/meson.build
index b6ef59a..e09a371 100644
--- a/lib/notifd/meson.build
+++ b/lib/notifd/meson.build
@@ -3,7 +3,7 @@ project(
   'vala',
   'c',
   version: run_command('cat', join_paths(meson.project_source_root(), 'version')).stdout().strip(),
-  meson_version: '>= 0.62.0',
+  meson_version: '>= 0.63.0',
   default_options: [
     'warning_level=2',
     'werror=false',
@@ -53,84 +53,28 @@ if get_option('lib')
     meson.project_name(),
     sources,
     dependencies: deps,
-    vala_args: ['--vapi-comments', '--ccode'],
+    vala_args: ['--vapi-comments'],
     vala_header: meson.project_name() + '.h',
     vala_vapi: meson.project_name() + '-' + api_version + '.vapi',
-    vala_gir: gir,
     version: meson.project_version(),
     install: true,
-    install_dir: [true, true, true, true],
+    install_dir: [true, true, true],
   )
 
-  # import('gnome').generate_gir(
-  #   lib,
-  #   sources: [],
-  #   nsversion: api_version,
-  #   namespace: namespace,
-  #   symbol_prefix: meson.project_name().replace('-', '_'),
-  #   identifier_prefix: namespace,
-  #   includes: ['GObject-2.0'],
-  #   header: meson.project_name() + '.h',
-  #   export_packages: meson.project_name() + '-' + api_version,
-  #   install: true,
-  # )
+  pkgs = []
+  foreach dep : deps
+    pkgs += ['--pkg=' + dep.name()]
+  endforeach
 
-  # custom_target(
-  #   gir,
-  #   command: [
-  #     find_program('g-ir-scanner'),
-  #     '--namespace=' + namespace,
-  #     '--nsversion=' + api_version,
-  #     '--library=' + meson.project_name(),
-  #     '--include=GObject-2.0',
-  #     '--output=' + gir,
-  #     '--symbol-prefix=' + meson.project_name().replace('-', '_'),
-  #     '--identifier-prefix=' + namespace,
-  #   ]
-  #   + pkgs
-  #   + ['@INPUT@'],
-  #   output: gir,
-  #   depends: lib,
-  #   input: meson.current_build_dir() / meson.project_name() + '.h',
-  #   install: true,
-  #   install_dir: get_option('datadir') / 'gir-1.0',
-  # )
-
-  # custom_target(
-  #   gir,
-  #   command: [
-  #     find_program('g-ir-scanner'),
-  #     '--namespace=' + namespace,
-  #     '--nsversion=' + api_version,
-  #     '--library=' + meson.project_name(),
-  #     '--include=GObject-2.0',
-  #     '--output=' + gir,
-  #     '--symbol-prefix=' + meson.project_name().replace('-', '_'),
-  #     '--identifier-prefix=' + namespace,
-  #   ]
-  #   + pkgs
-  #   + ['@INPUT@'],
-  #   input: lib.extract_all_objects(),
-  #   output: gir,
-  #   depends: lib,
-  #   install: true,
-  #   install_dir: get_option('datadir') / 'gir-1.0',
-  # )
-
-  # pkgs = []
-  # foreach dep : deps
-  #   pkgs += ['--pkg=' + dep.name()]
-  # endforeach
-  #
-  # gir_tgt = custom_target(
-  #   gir,
-  #   command: [find_program('valadoc'), '-o', 'docs', '--gir', gir] + pkgs + sources,
-  #   input: sources,
-  #   depends: lib,
-  #   output: gir,
-  #   install: true,
-  #   install_dir: get_option('datadir') / 'gir-1.0',
-  # )
+  gir_tgt = custom_target(
+    gir,
+    command: [find_program('python3'), files('gir.py'), gir] + pkgs + sources,
+    input: sources,
+    depends: lib,
+    output: gir,
+    install: true,
+    install_dir: get_option('datadir') / 'gir-1.0',
+  )
 
   custom_target(
     typelib,
@@ -142,7 +86,7 @@ if get_option('lib')
     ],
     input: lib,
     output: typelib,
-    depends: lib,
+    depends: [lib, gir_tgt],
     install: true,
     install_dir: get_option('libdir') / 'girepository-1.0',
   )
diff --git a/lib/notifd/notifd.vala b/lib/notifd/notifd.vala
index 6ca25fa..807e40a 100644
--- a/lib/notifd/notifd.vala
+++ b/lib/notifd/notifd.vala
@@ -1,5 +1,5 @@
 /**
- * Get the singleton instance of {@link Notifd}
+ * Get the singleton instance of [[email protected]]
  */
 namespace AstalNotifd {
     public Notifd get_default() {
@@ -74,7 +74,7 @@ public class AstalNotifd.Notifd : Object {
     }
 
     /**
-     * Gets the {@link Notification} with id or null if there is no such Notification.
+     * Gets the [[email protected]] with id or null if there is no such Notification.
      */
     public Notification get_notification(uint id) {
         return proxy != null ? proxy.get_notification(id) : daemon.get_notification(id);
@@ -85,7 +85,7 @@ public class AstalNotifd.Notifd : Object {
     }
 
     /**
-     * Emitted when the daemon receives a {@link Notification}.
+     * Emitted when the daemon receives a [[email protected]].
      *
      * @param id The ID of the Notification.
      * @param replaced Indicates if an existing Notification was replaced.
@@ -93,7 +93,7 @@ public class AstalNotifd.Notifd : Object {
     public signal void notified(uint id, bool replaced);
 
     /**
-     * Emitted when a {@link Notification} is resolved.
+     * Emitted when a [[email protected]] is resolved.
      *
      * @param id The ID of the Notification.
      * @param reason The reason how the Notification was resolved.
diff --git a/lib/notifd/notification.vala b/lib/notifd/notification.vala
index 5db3fe2..527a352 100644
--- a/lib/notifd/notification.vala
+++ b/lib/notifd/notification.vala
@@ -38,19 +38,24 @@ public class AstalNotifd.Notification : Object {
     public int expire_timeout { internal set; get; }
 
     /**
-     * List of {@link Action} of the notification.
+     * List of [[email protected]] of the notification.
      *
-     * Can be invoked by calling {@link Notification.invoke} with the action's id.
+     * Can be invoked by calling [[email protected]] with the action's id.
      */
     public List<Action?> actions { get { return _actions; } }
 
     /** Path of an image  */
     public string image { get { return get_str_hint("image-path"); } }
 
-    /** Indicates whether {@link Action} identifier should be interpreted as a named icon.  */
+    /**
+     * Indicates whether [[email protected]]
+     * identifier should be interpreted as a named icon.
+     */
     public bool action_icons { get { return get_bool_hint("action-icons"); } }
 
-    /** [[https://specifications.freedesktop.org/notification-spec/latest/categories.html|Category of the notification.]] */
+    /**
+     * [[https://specifications.freedesktop.org/notification-spec/latest/categories.html]]
+     */
     public string category { get { return get_str_hint("category"); } }
 
     /** Specifies the name of the desktop filename representing the calling program. */
@@ -71,13 +76,19 @@ public class AstalNotifd.Notification : Object {
     /** Indicates that the notification should be excluded from persistency. */
     public bool transient { get { return get_bool_hint("transient"); } }
 
-    /** Specifies the X location on the screen that the notification should point to. The "y" hint must also be specified.  */
+    /**
+     * Specifies the X location on the screen that the notification should point to.
+     * The "y" hint must also be specified.
+     */
     public int x { get { return get_int_hint("x"); } }
 
-    /** Specifies the Y location on the screen that the notification should point to. The "x" hint must also be specified.  */
+    /**
+     * Specifies the Y location on the screen that the notification should point to.
+     * The "x" hint must also be specified.
+     */
     public int y { get { return get_int_hint("y"); } }
 
-    /** {@link Urgency} level of the notification. */
+    /** [[email protected]] level of the notification. */
     public Urgency urgency { get { return get_byte_hint("urgency"); } }
 
     internal Notification(
@@ -141,24 +152,23 @@ public class AstalNotifd.Notification : Object {
     }
 
     /**
-     * Emitted when this {@link Notification} is resolved.
+     * Emitted when this this notification is resolved.
      *
      * @param reason The reason how the Notification was resolved.
      */
     public signal void resolved(ClosedReason reason);
 
     /**
-     * Emitted when the user dismisses this {@link Notification}
+     * Emitted when the user dismisses this notification.
      *
      * @see dismiss
      */
     public signal void dismissed();
 
     /**
-     * Emitted when an {@link Action} of this {@link Notification} is invoked.
+     * Emitted when an [[email protected]] of this notification is invoked.
      *
      * @param action_id id of the invoked action
-     * @see invoke
      */
     public signal void invoked(string action_id);
 
@@ -171,7 +181,7 @@ public class AstalNotifd.Notification : Object {
     public void dismiss() { dismissed(); }
 
     /**
-     * Invoke an {@link Action} of this {@link Notification}
+     * Invoke an [[email protected]] of this notification.
      *
      * Note that this method just notifies the client that this action was invoked
      * by the user. If for example this notification persists through the lifetime
diff --git a/nix/doc/gi-docgen.patch b/nix/doc/gi-docgen.patch
new file mode 100644
index 0000000..0ecb4bd
--- /dev/null
+++ b/nix/doc/gi-docgen.patch
@@ -0,0 +1,17 @@
+diff --git a/gidocgen/gir/parser.py b/gidocgen/gir/parser.py
+index e62835d..7ee60fa 100644
+--- a/gidocgen/gir/parser.py
++++ b/gidocgen/gir/parser.py
+@@ -288,7 +288,11 @@ class GirParser:
+ 
+         content = child.text or ""
+ 
+-        return ast.Doc(content=content, filename=child.attrib['filename'], line=int(child.attrib['line']))
++        return ast.Doc(
++            content=content,
++            filename=child.attrib.get('filename', ''),
++            line=int(child.attrib.get('line', 0)),
++        )
+ 
+     def _maybe_parse_source_position(self, node: ET.Element) -> T.Optional[ast.SourcePosition]:
+         child = node.find('core:source-position', GI_NAMESPACES)