doc: structure the portal documentation a bit better

src/modules/module-portal.c

@@ -46,6 +46,37 @@
 #include "pipewire/private.h"
 
 /** \page page_module_portal PipeWire Module: Portal
+ *
+ * The `portal` module performs access control management for clients started
+ * inside an XDG portal.
+ *
+ * The module connects to the session DBus and subscribes to
+ * `NameOwnerChanged` signals for the `org.freedesktop.portal.Desktop` name.
+ * The PID of the DBus name owner is the portal.
+ *
+ * A client connection from the portal PID to PipeWire gets assigned a \ref
+ * PW_KEY_ACCESS of `"portal"` and set to permissions ALL - it is the
+ * responsibility of the portal to limit the permissions before passing the
+ * connection on to the client. See \ref page_access for details on
+ * permissions.
+ *
+ * Clients connecting from other PIDs are ignored by this module.
+ *
+ * ## Module Options
+ *
+ * There are no module-specific options.
+ *
+ * ## General options
+ *
+ * There are no general options for this module.
+ *
+ * ## Example configuration
+ *\code{.unparsed}
+ * context.modules = [
+ *  {   name = libpipewire-portal }
+ * ]
+ *\endcode
+ *
  */
 
 #define NAME "portal"