Macros in synopses

Macros in synopses

[Sascha Wildner]

Hi,

how do people go about documenting macros in the SYNOPSIS? .Fn comes to 
mind of course, but I have some issues with it. Let me explain. Suppose 
a macro:

#define FOO_MODULE(name, evh)      \
static moduledata_t name##_mod = { \
     #name,                         \
     evh,                           \
     NULL                           \
};                                 \
DECLARE_MODULE(name, name##_mod, SI_SUB_PRE_DRIVERS, SI_ORDER_MIDDLE)

For a real function, you have explicit types for its arguments, for a 
macro, all you can do is derive them from what the macro does with them 
(which is usually possible).

So when I want to document my FOO_MODULE macro in my manual page, it 
would be (as per the members of the moduledata_t structure):

.Fn FOO_MODULE "const char *name" "modeventhand_t evh"

The problem with this is that 'name' is used with the # punctuator 
(stringify) in the macro's definition, so that the user can write

FOO_MODULE(bar, bar_mod_handler);

in his code with no quotation marks around the first argument. So if i 
documented it as being const char *, they might get the impression that 
they can do

FOO_MODULE("bar", bar_mod_handler);

Another option would be to write in the manpage:

.Fn FOO_MODULE "name" "modeventhand_t evh"

or

.Fn FOO_MODULE "name" "evh"

The latter seems to be the most popular way in existing manual pages.

"So, what's the fuzz all about?", you might think.

I do run scripts on the manual pages to check their "integrity" with the 
rest of DragonFly. Among them is a script that goes and constructs 
little C programs from the SYNOPSIS sections of .2, .3 and .9 manual 
pages and tries to compile them. This is to check whether the .In's in 
the SYNOPSIS are sufficient to define all the types used in the various 
function prototypes that follow. Now for macros (due to the issues 
described above) I always have to insert special code that checks if a 
type was given at all.

All in all I tend to think that using .Fn for macros is sub-optimal and 
I've more than once wished for a, say, .Ma mdoc macro for that purpose, 
so that something (e.g. scripts) going by the semantics of the mdoc 
macros used can more easily separate the two.

The intention of this mail is to find out what you others think/do about it.

Regards,
Sascha
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Macros in synopses

[Sascha Wildner]

On 7/29/2010 21:13, Sascha Wildner wrote:
> [...]

I should have called the subject actually "C macros in synopses".

Regards,
Sascha
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Macros in synopses

[Jukka Ruohonen]

On Thu, Jul 29, 2010 at 09:13:58PM +0200, Sascha Wildner wrote:
> For a real function, you have explicit types for its arguments, for a 
> macro, all you can do is derive them from what the macro does with them 
> (which is usually possible).

I have written few manual pages that document various macros. My conclusion
is that you should just use your own discretion with the types. I've often
left the type as an implicit note for the reader, doing something like:

	type
	MACRO(type parameter)

But perhaps what this really demonstrates is that one should avoid macros in
modern C.

> All in all I tend to think that using .Fn for macros is sub-optimal and 
> I've more than once wished for a, say, .Ma mdoc macro for that purpose, 
> so that something (e.g. scripts) going by the semantics of the mdoc 
> macros used can more easily separate the two.

In my opinion, if anything, the amount of macros should be decreased. I have
observed that people have difficulties even with .Fn (and when to use it
instead of e.g. .Nm or .Xr).

- Jukka.
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv