Change in libosmocore[master]: add API doc for LOGPFSM* macros

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

Neels Hofmeyr gerrit-no-reply at lists.osmocom.org
Wed Jan 2 23:29:17 UTC 2019


Neels Hofmeyr has posted comments on this change. ( https://gerrit.osmocom.org/12384 )

Change subject: add API doc for LOGPFSM* macros
......................................................................


Patch Set 2:

(1 comment)

https://gerrit.osmocom.org/#/c/12384/1/include/osmocom/core/fsm.h
File include/osmocom/core/fsm.h:

https://gerrit.osmocom.org/#/c/12384/1/include/osmocom/core/fsm.h@123
PS1, Line 123: osmo_fsm_inst
> I still think as long as we use asciidoc, we should use it properly ;)
I checked and in fact I am using it properly. If you verify the generated doxygen HTML, you will see that with this doc text, there already is a working cross link to struct osmo_fsm_inst.

- see doxygen doc for '\ref': "Creates a reference to a named section, subsection, page or anchor."
  \ref actually isn't about referencing documented data structures or functions!
  http://www.doxygen.nl/manual/commands.html#cmdref

- see doc for \a: "Displays the argument <word> in italics."
  \a is merely cosmetic, it doesn't affect cross referencing.
  http://www.doxygen.nl/manual/commands.html#cmda

(Notice also that there are misleading cross references. For example, the 'level' arg of this macro references the uint8_t level, member of struct gsmtap_osmocore_log_hdr.)

The bottom line is that in my opinion we should remove all '\a' and '\ref' from cross references to functions and structs. Only references to pages or subsections should remain.



-- 
To view, visit https://gerrit.osmocom.org/12384
To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings

Gerrit-Project: libosmocore
Gerrit-Branch: master
Gerrit-MessageType: comment
Gerrit-Change-Id: I3bf6500889aa58195f50a726dec0876c0c2baec3
Gerrit-Change-Number: 12384
Gerrit-PatchSet: 2
Gerrit-Owner: Neels Hofmeyr <nhofmeyr at sysmocom.de>
Gerrit-Reviewer: Harald Welte <laforge at gnumonks.org>
Gerrit-Reviewer: Jenkins Builder (1000002)
Gerrit-Reviewer: Neels Hofmeyr <nhofmeyr at sysmocom.de>
Gerrit-Reviewer: Vadim Yanitskiy <axilirator at gmail.com>
Gerrit-Comment-Date: Wed, 02 Jan 2019 23:29:17 +0000
Gerrit-HasComments: Yes
Gerrit-HasLabels: No
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20190102/36278197/attachment.htm>


More information about the gerrit-log mailing list