Doxygen code style

[Aleix Pol]

On Tue, Feb 19, 2019 at 12:00 PM Roman Gilg <subdiff at gmail.com> wrote:
>
> Commit
> https://phabricator.kde.org/R108:7b20e1f66f83657591001f473d31555c295e5569
> changes Doxygen comments style in KWin to the uniform pattern
>
> /**
>  *
>  **/
>
> with two stars at the end.
>
> Looking at upstream examples
> http://www.doxygen.nl/manual/docblocks.html#cppblock
> online examples
> https://mesos.readthedocs.io/en/latest/doxygen-style-guide/
> other projects
> https://gitlab.freedesktop.org/dbus/dbus/blob/master/dbus/dbus-connection.h
> and KDE frameworks
> https://cgit.kde.org/kio.git/tree/src/core/copyjob.h
> the preferred style though is
>
> /**
>  *
>  */
>
> with one star at the end.
>
> With one notable exception: KWayland, where the two-star pattern is
> used consistently.
> Also plasma-framework does mix both styles:
> https://cgit.kde.org/plasma-framework.git/tree/src/plasma/package.h
>
> I would like to uniformly use the one-star at the end pattern in
> KWin/KWayland and our other projects like upstream Doxygen suggests
> and other projects seem to adhere to most often, but want to get other
> opinions on that first.
>
> Cheers,
> Roman

Since we're intertwining Frameworks and Plasma, it could make sense to
choose one for Frameworks and stick with it.
It could be discussed in the frameworks list and included here:
https://techbase.kde.org/Policies/Frameworks_Coding_Style

I personally don't care much, your proposed solution makes sense to
me. A quick grep suggests both that it's the most common and that many
projects have the same issue you've seen.

Aleix

Aleix