HGKeeper

Bring back the break after functions
develop
2020-02-15, Richard Laager

d87c806b1f05

Bring back the break after functions

With the AlwaysBreak style, functions with many arguments get continued
onto the next line like this:

gplugin_gtk_store_plugin_unloaded_cb(
GObject *manager,
GPluginPlugin *plugin,
gpointer data) {
gplugin_gtk_store_update_plugin_state(
GPLUGIN_GTK_STORE(data), plugin);
}

It is difficult to see where parameters stop and the body starts.

Gary suggested this formatting, which "helps (at least me) visually see
the blocks while scanning the code":

gplugin_gtk_store_plugin_unloaded_cb(
GObject *manager,
GPluginPlugin *plugin,
gpointer data
) {
gplugin_gtk_store_update_plugin_state(
GPLUGIN_GTK_STORE(data), plugin);
}

Unfortunately, that is not something that clang-format supports. We
can get almost the same output (just moving the closing paren), with
the same visual benefits, by using BraceWrapping: AfterFunction: true,
which produces this:

gplugin_gtk_store_plugin_unloaded_cb(
GObject *manager,
GPluginPlugin *plugin,
gpointer data)
{
gplugin_gtk_store_update_plugin_state(
GPLUGIN_GTK_STORE(data), plugin);
}

## 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

```

## hgflow

GPlugin uses [hgflow][3] for development. All development takes place on the

develop branch which leaves default to be a stable release clone. All long

term feature/bug fix work should take place on a feature branch that when

closed, gets merged to develop.

Releases are forked from develop and create a new branch for any testing/bug

fixes. When a release is deemed done, it's merged back into develop and into

default. hgflow takes care of all of this for us.

To add a feature please clone `https://keep.imfreedom.org/gplugin/gplugin`.

Once you have your fork cloned and hgflow setup and installed, type:

```

hg flow feature start $NAME_OF_YOUR_FEATURE$

```

This will create a new branch for you to do your work on. When your work has

been completed, please open a review request at

[reviews.imfreedom.org](https://reviews.imfreedom.org).

[1]: https://clang.llvm.org/docs/ClangFormat.html

[2]: https://hg.mozilla.org/projects/nss/file/default/coreconf/precommit.clang-format.sh

[3]: https://hg.sr.ht/~wu/hgflow