5 Dec
2018
5 Dec
'18
12:21 p.m.
On Wed, Dec 05, 2018 at 08:59:29AM +0100, Harald Welte wrote:
Even for explicit \brief, you should still end the sentence in a dot. One of
the two: either the same (next line bleeds into \brief) or we had a problem if
the first summary spans more than one line and was cut off by \brief?
In any case, the logic was so that I came to the conclusion that without having
to write '\brief', things were more or less similar.
But I really don't understand why anyone would write an API comment and choose
to not end a sentence in a full-stop, and why many of you particularly do that
for the first sentence only. That's a very weird social phenomenon :P
My particular taste problem with '\brief' was that I dislike any and all of the
doxygen formatting breaking the flow of reading API and writing doc in C
comment. Worst of all is '\a', it reads like the english 'a', and totally
messes up reading. Shouldn't be that hard for doxygen to just automatically
find all the defined names and highlight them.
yep, also just noticed, thx
~N
- there is
no way to make sure the initial summary is ended in '.',
because the script cannot understand human semantics.
that's the problem with "autobrief", right? doesn't your brain automatically remove those by
now when reading?
They reliably throw me off every time. Maybe because my personal nature tends
towards "too obsessed with details".
libosmocore
is the only git tree actually building doxygen docs.
That's not entirely true:
http://ftp.osmocom.org/api/latest/ lists also libosmo-netif, libosmo-sccp, libosmo-dsp
and even osmo-gmr (Sylvain!)