Re: [docbook] Function prototype comments

[Russell Shaw <rjshaw@netspace.net.au>]

Michael Smith wrote:
> Russell Shaw <rjshaw@netspace.net.au> writes:
> 
>>Where do i put parameter comments (/*...*/) in function prototypes?
>>When i try it, the semicolons come after the comments instead of after
>>the parameters:
>>
>>XkbDoodadPtr XkbAddGeomDoodad(geom,
>>                              section,
>>                              name);
>>
>>XkbGeometryPtr geom /* geometry to which the doodad is added */;
>>XkbSectionPtr  section /* section, if any, to which the doodad is added */;
>>Atom           name /* name of the new doodad */;
> 
> 
> I am not sure what the expected behavior should be. Consider the
> following example:
> 
>   <paramdef>char *<parameter>a</parameter>[]</paramdef>
> 
> When that's rendered, where should semicolon go?
> 
> I guess the problem is that DocBook does not provide any way to
> mark up comments as part of param definitions. It treats text
> within a Paramdef before and after the Parameter as part of the
> parameter definition.
> 
> The way it is now, the stylsheets have no way to know whether the
> stuff after the Parameter is a comment, or a part of the Paramdef.
> 
> I guess we could have them search through any text after the
> Parameter and look for instances of a "/*" delimiter, and if
> found, render that text after the semicolon.
> 
>   --Mike

How evolving is the docbook standard? Could new things be added like:

<funcprototype>
   <paramdef>char *<parameter>a</parameter>[]</paramdef>/* comment */
   <paramdef>char *<parameter>a</parameter>[]</paramdef><para>/* para comment */</para>
</funcprototype>