Merge pull request sailfishos-patches#448 from nephros/documentation

Document all the things II

.gitignore

@@ -17,3 +17,4 @@ patchmanager-dialog
 src/icons/z*
 src/icons/ss
 *.list
+doc/generated

README.md

@@ -33,8 +33,8 @@ Usually, you can generate such patch file using the following command, with the
 
 The metadata file contains information about a Patch.  It is a simple JSON file, that must be named `patch.json`.
 This file contains the title of the Patch, a short description of the Patch, a category, and additional information.  For the documentation of this JSON file format see:
- - for the [modern format](./doc/example_patch.json.md)
- - for the much simpler [legacy format](./doc/example_legacy_patch.json.md)
+ - for the [modern format](./doc/examples/patch.json.md)
+ - for the much simpler [legacy format](./doc/examples/legacy_patch.json.md)
 
 Either format is supported, but the modern one provides more useful features and is recommended.
 

doc/qdoc/common.qdocconf

@@ -0,0 +1,34 @@
+# include some Qt defaults
+# -- macros for QDoc commands
+include($QT_INSTALL_DOCS/global/macros.qdocconf)
+# -- needed by C++ projects
+include($QT_INSTALL_DOCS/global/qt-cpp-defines.qdocconf)
+# -- compatibility macros
+include($QT_INSTALL_DOCS/global/compat.qdocconf)
+# -- configuration common among QDoc projects
+include($QT_INSTALL_DOCS/global/fileextensions.qdocconf)
+# -- offline HTML template for documentation shipped to Qt Creator
+#include($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf)
+include($SAILFISH_INSTALL_DOCS/sailfish-html-templates.qdocconf)
+
+# Reduce padding around code
+codeprefix         = "\n"
+codesuffix         = "\n"
+
+# override/add some things to the stylesheets:
+HTML.stylesheets  += ./pm.css
+
+# assign custom HTML footer to replace Qt's default copyright notice
+HTML.footer = "<div align='center'><hr/>" \
+              "<p><small>Patchmanager Documentation\n" \
+              "Copyright (c) 2023 Patchmanager for SailfishOS contributors.\n" \
+              "This document may be used under the terms of the " \
+              "<a href='https://spdx.org/licenses/CC-BY-SA-4.0.html'>" \
+              "Creative Commons Attribution Share Alike 4.0 International</a> " \
+              "License.</small></p>" \
+              "<p/></div>"
+
+navigation.homepage = https://github.com/sailfishos-patches/patchmanager/wiki
+navigation.hometitle = Patchmanager
+navigation.landingpage = Patchmanager Documentation
+

doc/qdoc/daemon.qdocconf

@@ -0,0 +1,13 @@
+project         = daemon
+description     = Patchmanager Daemon Reference Documentation
+versionsym      =
+version         = 2.0
+url             = https://github.com/sailfishos-patches/patchmanager
+
+include (common.qdocconf)
+
+headerdirs += ../../src/bin/patchmanager-daemon
+headers.fileextensions = "*.h *.hpp"
+
+sourcedirs += ../../src/bin/patchmanager-daemon
+#sources.fileextensions = "*.cpp *.qdoc *.qml"

doc/qdoc/dialog.qdocconf

@@ -0,0 +1,10 @@
+project         = dialog
+description     = Patchmanager Startup Dialog Documentation
+versionsym      =
+version         = 2.0
+url             = https://github.com/sailfishos-patches/patchmanager
+
+include (common.qdocconf)
+
+sourcedirs = ../../src/bin/dialog
+

doc/qdoc/general.qdocconf

@@ -0,0 +1,10 @@
+project = patchmanager
+description = Patchmanager
+
+include (common.qdocconf)
+
+## Sources
+sources += ../../src/index.qdoc
+# for quoting
+exampledirs += ../../src/bin/patchmanager-daemon
+

doc/qdoc/master.qdocconf

@@ -0,0 +1,6 @@
+doc/qdoc/general.qdocconf
+doc/qdoc/qmlplugin.qdocconf
+doc/qdoc/daemon.qdocconf
+doc/qdoc/plugin.qdocconf
+doc/qdoc/preload.qdocconf
+doc/qdoc/dialog.qdocconf

doc/qdoc/plugin.qdocconf

@@ -0,0 +1,11 @@
+project         = settings-plugin
+description     = Patchmanager Settings Plugin Documentation
+versionsym      =
+version         = 2.0
+url             = https://github.com/sailfishos-patches/patchmanager
+
+include (common.qdocconf)
+
+sourcedirs = ../../src/plugin
+
+

doc/qdoc/pm.css

@@ -0,0 +1,5 @@
+a:link { color: #8C001A; text-decoration: none; text-align: left; }
+a.qa-mark:target:before { content: "***"; color: #ff0000; }
+a:hover { color: #8C0060; text-align: left; }
+a:visited { color: #8C001A; text-align: left; }
+a:visited:hover { color: #8C0060; text-align: left; }

doc/qdoc/preload.qdocconf

@@ -0,0 +1,13 @@
+project         = preload
+description     = Patchmanager Preload Library
+versionsym      =
+version         = 2.0
+url             = https://github.com/sailfishos-patches/patchmanager
+
+include(common.qdocconf)
+
+sources = ../../src/preload/src/preloadpatchmanager.qdoc
+# needed for quoting source code:
+exampledirs += ../../src/preload/src
+
+

doc/qdoc/qmlplugin.qdocconf

@@ -0,0 +1,19 @@
+project         = qml-plugin
+description     = Patchmanager QML Plugin Reference Documentation
+versionsym      =
+version         = 2.0
+url             = https://github.com/sailfishos-patches/patchmanager
+
+include(common.qdocconf)
+
+depends += qtcore qtqml
+
+headerdirs = ../../src/qml
+#headers.fileextensions = "*.h *.hpp"
+
+sourcedirs = ../../src/qml
+sources += qmlplugin.qdoc
+#sources.fileextensions = "*.cpp *.qdoc *.qml"
+
+# get rid of warnings about undoicumented stuff in patchmanager.h
+Cpp.ignoretokens += Q_PROPERTY

makedocs

@@ -0,0 +1,65 @@
+#!/bin/sh
+#
+# Copyright (c) 2023, Peter G. "nephros" <[email protected]>
+# Licensed under the terms of the BSD 3-Clause License
+#
+
+# This will build Documentation.
+#
+# It is intended to be run from within the source tree.
+# It is also used in Github Actions.
+#
+# Note that there are large differnces in the qdoc command between Qt 5.6
+# (SFOS), and later Qt versions.
+# In order to enable building in newer Qt versions, changes in both the qdoc
+# config files as well as the code comments will be required.
+
+echo '####### $0 starting... #######'
+switched_dirs="false"
+if gitroot=$(git rev-parse --show-toplevel 2>/dev/null); then
+	echo found a git root at $gitroot, running from there...
+	pushd $gitroot 2>/dev/null || cd $gitroot
+	switched_dirs="true"
+else
+	echo this is not a git repo, assuming root is \$PWD
+fi
+
+# this is searched relative to the qdocconf file!!
+export SAILFISH_INSTALL_DOCS=sailfish-qdoc-template/config
+
+### verify "build" environment
+echo Verifying build environment...
+qdoc --version
+if [ $? -ne 0 ]; then
+  echo ERROR: qdoc does not seem to work! Please check your qt5 installation
+  exit 1
+fi
+if [ ! -e doc/qdoc/sailfish-qdoc-template ]; then
+  echo ERROR: sailfish-qdoc-template does not exist
+  echo You should "'git clone --depth 1 -b upgrade-4.5.0 https://github.com/sailfishos/sailfish-qdoc-template doc/qdoc/sailfish-qdoc-template'"
+  exit 1
+fi
+
+OUT=$PWD/doc/generated
+
+export QT_VER=5
+export QT_INSTALL_DOCS
+
+if [ -z "$QT_INSTALL_DOCS" ]; then
+	if [ -f /usr/share/doc/qt5/global/macros.qdocconf ]; then
+		QT_INSTALL_DOCS=/usr/share/doc/qt5
+	elif [ -f /usr/share/qt5/doc/global/macros.qdocconf ]; then
+		QT_INSTALL_DOCS=/usr/share/qt5/doc
+	fi
+fi
+
+echo Generating Docs...
+[ -d $OUT ] && rm -r $OUT
+qdoc --no-examples --outputdir $OUT --outputformat HTML --installdir $QMAKE_INSTALL_ROOT/doc doc/qdoc/master.qdocconf --single-exec  $@
+echo Generated Docs at "$OUT"
+
+[ $switched_dirs = "true" ] && popd 2>/dev/null || cd -
+
+echo '####### $0 done. #######'
+# always exit 0 for CI runs:
+exit 0

src/bin/dialog/dialog.qdoc

@@ -0,0 +1,55 @@
+/*!
+  \title Patchmanager Documentation: Startup Dialog
+  \page index.html overview
+  \indexpage Patchmanager Documentation
+
+  This is a very simple Sailfish OS application that upon start checks the state of the Patchmanager Daemon to see whether it needs to launch a GUI.
+
+  \section1 User Interface: Dialog
+
+  At start it shows a \l {https://sailfishos.org/develop/docs/silica/qml-sailfishsilica-sailfish-silica-remorseitem.html/}{RemorseItem}
+  with a timeout of 10 seconds. If the user cancels this dialog, the PM deamon
+  will not activate any patches (with the side-effect of marking all as
+  disabled.)
+
+  If the Remorse timer runs out, the PM daemon will activate all Patches marked
+  as enabled, and the Dialog shows a little progress bar while it's
+  doing that.
+
+  Patches failing to apply will be logged, and reported.
+
+  After ending any of the above operations, a \uicontrol "Quit" button is
+  activated which will close the application.
+
+  This dialog will only be shown if the option \uicontrol{"Apply on Boot"} is \c off.
+
+
+  \section1 Application Startup
+
+  Upon launch, the binary will check the following:
+
+  \list
+  \li whether \l {PatchManager::applyOnBoot}{applyOnBoot} is set in \c /etc/patchmanager2.conf.
+  \li the result of a call to the \l {PatchManagerObject::getLoaded}{getLoaded} D-Bus method on the Daemon.
+  \endlist
+
+  If the first is set to \c true, it will exit. (Because with this setting on, all patches will be activate at boot, without the need of a Startup Dialog.)
+
+  If the reply indicates that PM has not been initialized, it will launch the QML UI.  Otherwise it will exit.
+
+  \section2 D-Bus interface
+
+   The dialog implements a D-Bus method \c show i on the root path of the \c org.SfietKonstantin.patchmanager service to invoke the UI:
+
+     \badcode
+     <interface name="org.SfietKonstantin.patchmanager">
+       <method name="show">
+           <annotation name="org.freedesktop.DBus.Method.NoReply" value="true"/>
+       </method>
+     </interface>
+     \endcode
+
+   This is used by \l {PatchManagerObject::lipstickChanged} to open the dialog once it has initialized.
+
+   \sa {Patchmanager Services}, {Patchmanager Configuration Files}
+*/

src/bin/patchmanager-daemon/daemon.qdoc

@@ -0,0 +1,24 @@
+/*!
+  \page index.html
+
+  \title Patchmanager Documentation: Daemon
+  \indexpage Patchmanager Documentation
+
+    \section1 Overview
+
+    A D-Bus activated background service which manages patch un/installation,
+    listing, de/actvation, and communication with the preload library.
+
+    Patchmanager is usually launched by its DBus service.
+
+    If the \c patchmanager binary is called from command line, it
+    can also serve as a simple CLI to a running daemon.
+    See the output of \c{patchmanager --help} and
+    PatchManagerObject::process() for more information.
+
+    \section2 Documentation:
+    \generatelist {classesbymodule PatchManagerDaemon}
+
+
+*/
+

src/bin/patchmanager-daemon/inotifywatcher.cpp

@@ -69,6 +69,20 @@ INotifyWatcher::INotifyWatcher(QObject *parent)
     connect(notifier, &QSocketNotifier::activated, this, &INotifyWatcher::readFromInotify);
 }
 
+/*! \class INotifyWatcher
+    \inmodule PatchManagerDaemon
+    \inherits QSocketNotifier
+    \brief watches a list of files or directories for changes
+*/
+/*! \fn void INotifyWatcher::directoryChanged(const QString &path, bool removed);
+    \fn void INotifyWatcher::fileChanged(const QString &path, bool removed);
+    This signal is emitted when a file or directory has changed.
+    Parameters are the \a path and whether it was \a removed.
+ */
+/*! \fn void INotifyWatcher::contentChanged(const QString &path, bool created);
+    This signal is emitted when directory content has changed
+    Parameters are the \a path and whether something was \a created.
+ */
 INotifyWatcher::~INotifyWatcher()
 {
     notifier->setEnabled(false);
@@ -78,6 +92,7 @@ INotifyWatcher::~INotifyWatcher()
     ::close(inotifyFd);
 }
 
+/*! Add \a paths to the list of paths to be watched. */
 QStringList INotifyWatcher::addPaths(const QStringList &paths)
 {
     QStringList p = paths;
@@ -127,6 +142,7 @@ QStringList INotifyWatcher::addPaths(const QStringList &paths)
     return p;
 }
 
+/*! Removes \a paths from the list of paths to be watched. */
 QStringList INotifyWatcher::removePaths(const QStringList &paths)
 {
     QStringList p = paths;

src/bin/patchmanager-daemon/journal.cpp

@@ -4,6 +4,12 @@
 #include <QDebug>
 #include <stdio.h>
 
+/*! \class Journal
+    \inmodule PatchManagerDaemon
+*/
+/*! \fn Journal::matchFound()
+   Emitted when the fileters found a log entry that matched.
+*/
 Journal::Journal(QObject *parent)
     : QObject(parent)
 {
@@ -39,6 +45,7 @@ void Journal::wait()
     thread->start();
 }
 
+/*! Attaches itself to the Journal, filetering for \e Lipstick and \e jolla-settings executables. */
 void Journal::init()
 {
     qDebug() << Q_FUNC_INFO;
@@ -60,6 +67,16 @@ void Journal::init()
     wait();
 }
 
+/*! Read the message from the Journal, look got certain strings, and emit the matchFound signal if found.
+
+  Strings looked for are:
+
+  \list
+    \li   "Type X unavailable"
+    \li   "is not a type" AND "Error while loading page"
+  \endlist
+
+*/
 void Journal::process()
 {
     int next_ret = sd_journal_next(m_sdj);