Re: [Xenomai-help] doc patch: RT_TASK_INFO

[Jan Kiszka <jan.kiszka@domain.hid>]

[-- Attachment #1: Type: text/plain, Size: 1841 bytes --]

Nathaniel Villaume wrote:
> The patches were to help you out! I thought that maybe you wouldn't want
> RT_TASK documented -- users don't really need to konw about magic number
> and flowgen, do they?  But yeah, sorry for the spamming.

Yes, I absolutely agree with you that RT_TASK and other internal
structures should not pop up in doxygen (but, of course, still have its
comments for the developers)!

> 
> As for the comment style, the C style comments don't show up using this
> inline method: /*!< */   -- that was part of the original problem.  One

Mm, not convinced yet: the original code looked like this: /* !< Text */
(note the space). I think there must be a C-conforming way to document
fields.

> solution is to use the @typedef command. The only drawback here is the
> minor replication. For example:
> 
> /*! @typedef RT_TASK
>    @brief Contains important data
>  @param  magic  Magic uniquely identifies the task's wizardry ancestry
>  @param  prio   task priority
> */
> typedef struct {
>  int magic;  // Must come first!   (comments don't HAVE to go here)
>  uint prio;  // task priority
>  /* etc */
> } RT_TASK;

No, not really beautiful. Another way is this (see also RTDM skin):

typedef struct {
	/** Some field */
	int some_field;
} my_struct;

The problem with doxygen is that you never really know what went wrong,
at least not within the first hours of experimenting with the code... :(

> 
> What I need to know from you:
> 1) Do you care about this duplication of struct member-names (harder to
> keep docs synchronized with code)?

I would personally prefer to avoid this.

> 2) Do you want RT_TASK member documentation to show up in
> doxygen-generated pages?  (this lets me know what to change)

See above. But I'm not the only one around here.

Jan


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 250 bytes --]