gplugin/gplugin

Fix cross-referencing in gplugin docs

2021-10-06, Elliott Sales de Andrade
ef60f88bb66d
Fix cross-referencing in gplugin docs

gi-docgen already puts types on most documented things. Thus most of this is replacing the linking with normal text.

But otherwise things are linked into GLib, internally, etc.


* Improve documentation of manager
For parameters, dropped the types because gi-docgen shows them automatically. It also shows transfer full, etc., so don't write extra notes about referencing and freeing.
The types are not correctly shown on signals, which _are_ kept in docs.
Also, break up some paragraphs so that the details are not shown in the summaries on the overview page for the Manager.
* Clean up loader docs
Most of the links are not needed, so this just makes them normal text.
* Fix doc cross-references in plugin info
Like before, most of this is actually _removing_ extra cross-references, but there are still one or two left.
* Clean up cross references in plugin interface
* Fix cross-referencing in top-level functions

Testing Done:
Compiled and looked at docs in the browser.

Reviewed at https://reviews.imfreedom.org/r/999/
## clang-format
GPlugin uses [clang-format][1] to automatically format code. Version 9 (or
higher) is required. Earlier versions will fail on the options in the
`.clang-format` file.
You can use clang-format in one or more of the following ways:
* Integrate it into your editor. The [clang-format page][1] has examples.
* Use a Mercurial [hook script][2].
* Run `ninja clang-format` from your build directory.
* Worst case, run `clang-format -i SOME_FILE` manually.
### GObject Functions
GObject and GPlugin have functions which take pairs of name/value arguments:
* `g_object_get()`
* `g_object_new()`
* `gplugin_plugin_info_new()`
If code calling one of these functions with such pairs has to be wrapped, the
pairs are easier to read and edit with manual formatting to group the name and
value on the same line (but otherwise following the usual formatting that
clang-format would apply):
```
/* clang-format off */
g_object_get(
G_OBJECT(info),
"name", &name,
"summary", &summary,
NULL);
/* clang-format on */
```
### Debian
Debian and derivatives (e.g. Ubuntu) ship clang-format version 9 in a package
named `clang-format-9`. The package named `clang-format` is currently an
older version. Additionally, the `clang-format-9` package will not place a
`clang-format` in the `$PATH`. Install as follows:
```
sudo apt install clang-format-9
sudo update-alternatives --set clang-format /usr/bin/clang-format-9
```
## convey
GPlugin uses [Convey][3] for CI. You can run the integration tests locally.
To initially setup Convey, which requires Docker:
1. Install Convey. You can use a pre-built binary from [convey's Downloads
page][4]; put that (or a symlink) in your `$PATH` named `convey`.
For now, avoid version 0.14.
2. Install Docker. On Debian systems, use: `sudo apt install docker.io`
3. Add yourself to the `docker` group. Adding yourself to a group does not
add that group to your existing session, so the first time you will need to
get a shell in that group with `newgrp docker` or by rebooting.
To run all of the integration tests, run the "all" metaplan:
```
convey all
```
To run a specific test/platform, run the plan directly:
```
convey alpine-edge-amd64
```
To get a list of metaplans and their plans:
```
convey list metaplans
```
[1]: https://clang.llvm.org/docs/ClangFormat.html
[2]: https://hg.mozilla.org/projects/nss/file/default/coreconf/precommit.clang-format.sh
[3]: https://keep.imfreedom.org/grim/convey
[4]: https://bintray.com/pidgin/releases/convey