[Xenomai-core] [PATCH] fix doxygen complaints

[Xenomai-core] [PATCH] fix doxygen complaints

[Jan Kiszka]

[-- Attachment #1.1: Type: text/plain, Size: 0 bytes --]



[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: doxy-fixes.patch --]
[-- Type: text/x-patch; name="doxy-fixes.patch", Size: 5971 bytes --]

Index: xenomai/ksrc/skins/posix/clock.c
===================================================================
--- xenomai/ksrc/skins/posix/clock.c	(Revision 2902)
+++ xenomai/ksrc/skins/posix/clock.c	(Arbeitskopie)
@@ -139,10 +139,10 @@ int clock_gettime(clockid_t clock_id, st
  *
  * This allow setting the CLOCK_REALTIME clock.
  *
- * @param clock_id, the id of the clock to be set, only CLOCK_REALTIME is
+ * @param clock_id the id of the clock to be set, only CLOCK_REALTIME is
  * supported.
  *
- * @param tp, the address of a struct timespec specifying the new date.
+ * @param tp the address of a struct timespec specifying the new date.
  *
  * @retval 0 on success;
  * @retval -1 with @a errno set if:
Index: xenomai/ksrc/arch/generic/hal.c
===================================================================
--- xenomai/ksrc/arch/generic/hal.c	(Revision 2902)
+++ xenomai/ksrc/arch/generic/hal.c	(Arbeitskopie)
@@ -173,7 +173,7 @@ int rthal_irq_request(unsigned irq,
 
 /**
  * @fn int rthal_irq_release(unsigned irq)
- *                           
+ *
  * @brief Uninstall a real-time interrupt handler.
  *
  * Uninstalls an interrupt handler previously attached using the
@@ -208,7 +208,7 @@ int rthal_irq_release(unsigned irq)
 
 /**
  * @fn int rthal_irq_host_request(unsigned irq,rthal_irq_host_handler_t handler,char *name,void *dev_id)
- *                           
+ *
  * @brief Install a shared Linux interrupt handler.
  *
  * Installs a shared interrupt handler in the Linux domain for the
@@ -244,7 +244,7 @@ int rthal_irq_release(unsigned irq)
 
 /**
  * @fn int rthal_irq_host_release (unsigned irq,void *dev_id)
- *                           
+ *
  * @brief Uninstall a shared Linux interrupt handler.
  *
  * Uninstalls a shared interrupt handler from the Linux domain for the
@@ -274,7 +274,7 @@ int rthal_irq_release(unsigned irq)
 
 /**
  * @fn int rthal_irq_host_pend (unsigned irq)
- *                           
+ *
  * @brief Propagate an IRQ event to Linux.
  *
  * Causes the given IRQ to be propagated down to the Adeos pipeline to
@@ -304,13 +304,13 @@ int rthal_irq_host_pend(unsigned irq)
 
 /**
  * @fn int rthal_irq_affinity (unsigned irq,cpumask_t cpumask,cpumask_t *oldmask)
- *                           
+ *
  * @brief Set/Get processor affinity for external interrupt.
  *
  * On SMP systems, this service ensures that the given interrupt is
  * preferably dispatched to the specified set of processors. The
  * previous affinity mask is returned by this service.
- * 
+ *
  * @param irq The interrupt source whose processor affinity is
  * affected by the operation. Only external interrupts can have their
  * affinity changed/queried, thus virtual interrupt numbers allocated
@@ -320,7 +320,7 @@ int rthal_irq_host_pend(unsigned irq)
  * representing the new affinity for this interrupt. A zero value
  * cause this service to return the current affinity mask without
  * changing it.
- * 
+ *
  * @param oldmask If non-NULL, a pointer to a memory area which will
  * bve overwritten by the previous affinity mask used for this
  * interrupt source, or a zeroed mask if an error occurred.  This
@@ -365,7 +365,7 @@ int rthal_irq_affinity(unsigned irq, cpu
 
 /**
  * @fn int rthal_trap_catch (rthal_trap_handler_t handler)
- *                           
+ *
  * @brief Installs a fault handler.
  *
  * The HAL attempts to invoke a fault handler whenever an uncontrolled
@@ -930,7 +930,7 @@ unsigned long long __rthal_generic_full_
 
 /**
  * @fn int rthal_irq_enable(unsigned irq)
- *                           
+ *
  * @brief Enable an interrupt source.
  *
  * Enables an interrupt source at PIC level. Since Adeos masks and
@@ -961,7 +961,7 @@ unsigned long long __rthal_generic_full_
 
 /**
  * @fn int rthal_irq_disable(unsigned irq)
- *                           
+ *
  * @brief Disable an interrupt source.
  *
  * Disables an interrupt source at PIC level. After this call has
@@ -986,8 +986,10 @@ unsigned long long __rthal_generic_full_
  * - Any domain context.
  */
 
-/*! 
- * \fn int rthal_timer_request(void (*tick_handler) (void), void (*mode_emul)(int mode, void *tdev), int (*tick_emul)(unsigned long delay, void *tdev), int cpu)
+/**
+ * \fn int rthal_timer_request(void (*tick_handler)(void),
+ *             void (*mode_emul)(enum clock_event_mode mode, struct ipipe_tick_device *tdev),
+ *             int (*tick_emul)(unsigned long delay, struct ipipe_tick_device *tdev), int cpu)
  * \brief Grab the hardware timer.
  *
  * rthal_timer_request() grabs and tunes the hardware timer in oneshot
@@ -1036,8 +1038,8 @@ unsigned long long __rthal_generic_full_
  * - Linux domain context.
  */
 
-/*! 
- * \fn void rthal_timer_release(void)
+/**
+ * \fn void rthal_timer_release(int cpu)
  * \brief Release the hardware timer.
  *
  * Releases the hardware timer, thus reverting the effect of a
@@ -1045,6 +1047,8 @@ unsigned long long __rthal_generic_full_
  * is shared with Linux, a periodic setup suitable for the Linux
  * kernel will be reset.
  *
+ * @param cpu The CPU number the timer was grabbed from.
+ *
  * Environments:
  *
  * This service can be called from:
Index: xenomai/doc/doxygen/Doxyfile-common.in
===================================================================
--- xenomai/doc/doxygen/Doxyfile-common.in	(Revision 2902)
+++ xenomai/doc/doxygen/Doxyfile-common.in	(Arbeitskopie)
@@ -690,7 +690,8 @@ PREDEFINED             = DOXYGEN_CPP \
         CONFIG_XENO_OPT_POSIX_INTR \
         CONFIG_XENO_OPT_RTAI_FIFO \
         CONFIG_XENO_OPT_RTAI_SEM \
-        CONFIG_XENO_OPT_RTAI_SHM
+        CONFIG_XENO_OPT_RTAI_SHM \
+        CONFIG_GENERIC_CLOCKEVENTS
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
 # this tag can be used to specify a list of macro names that should be expanded. 

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

Re: [Xenomai-core] [PATCH] fix doxygen complaints

[Gilles Chanteperdrix]

> -/*!
> - * \fn int rthal_timer_request(void (*tick_handler) (void), void (*mode_emul)(int mode, void *tdev), int (*tick_emul)(unsigned long delay, void *tdev), int cpu)
> +/**
> + * \fn int rthal_timer_request(void (*tick_handler)(void),
> + *             void (*mode_emul)(enum clock_event_mode mode, struct ipipe_tick_device *tdev),
> + *             int (*tick_emul)(unsigned long delay, struct ipipe_tick_device *tdev), int cpu)

Doxygen does not like when the function arguments are not on one line.
At least some version that was used in the past.


-- 
                                               Gilles Chanteperdrix

Re: [Xenomai-core] [PATCH] fix doxygen complaints

[Jan Kiszka]

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

Gilles Chanteperdrix wrote:
>> -/*!
>> - * \fn int rthal_timer_request(void (*tick_handler) (void), void (*mode_emul)(int mode, void *tdev), int (*tick_emul)(unsigned long delay, void *tdev), int cpu)
>> +/**
>> + * \fn int rthal_timer_request(void (*tick_handler)(void),
>> + *             void (*mode_emul)(enum clock_event_mode mode, struct ipipe_tick_device *tdev),
>> + *             int (*tick_emul)(unsigned long delay, struct ipipe_tick_device *tdev), int cpu)
> 
> Doxygen does not like when the function arguments are not on one line.
> At least some version that was used in the past.
> 

Hmm, I was using Doxygen 1.5.0 here, and there were neither complaints
during compile-time nor obvious quirks in the output. Maybe this issue
got fixed in the meantime. What was the precise effect?

Jan


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

Re: [Xenomai-core] [PATCH] fix doxygen complaints

[Gilles Chanteperdrix]

On 8/10/07, Jan Kiszka <jan.kiszka@domain.hid> wrote:
> Gilles Chanteperdrix wrote:
> >> -/*!
> >> - * \fn int rthal_timer_request(void (*tick_handler) (void), void (*mode_emul)(int mode, void *tdev), int (*tick_emul)(unsigned long delay, void *tdev), int cpu)
> >> +/**
> >> + * \fn int rthal_timer_request(void (*tick_handler)(void),
> >> + *             void (*mode_emul)(enum clock_event_mode mode, struct ipipe_tick_device *tdev),
> >> + *             int (*tick_emul)(unsigned long delay, struct ipipe_tick_device *tdev), int cpu)
> >
> > Doxygen does not like when the function arguments are not on one line.
> > At least some version that was used in the past.
> >
>
> Hmm, I was using Doxygen 1.5.0 here, and there were neither complaints
> during compile-time nor obvious quirks in the output. Maybe this issue
> got fixed in the meantime. What was the precise effect?

I do not remember, either some random parse error, or maybe the
function documentation not appearing in the output.

-- 
                                               Gilles Chanteperdrix