Re: [cdi-devel] [PATCH] Documentation: Document and translate cdi.h

[Rich Edelman <redelman@xxxxxxxxx>]

On Wed, Dec 30, 2009 at 4:21 PM, Kevin Wolf <kevin@xxxxxxxxxx> wrote:
> + Add module documentation for Core module
> + Add some more doxygen commits in cdi.h
> + Add English translations for comments in cdi.h
>
> Signed-off-by: Kevin Wolf <kevin@xxxxxxxxxx>
> ---
>  include/cdi.h |  204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 files changed, 196 insertions(+), 8 deletions(-)
>
> diff --git a/include/cdi.h b/include/cdi.h
> index d7cd210..629bbd1 100644
> --- a/include/cdi.h
> +++ b/include/cdi.h
> @@ -62,30 +225,55 @@ struct cdi_driver {
>  };
>
>  /**
> - * Muss vor dem ersten Aufruf einer anderen CDI-Funktion aufgerufen werden.
> + * \german
> + * Treiber, die ihre eigene main-Funktion implemenieren, müssen diese Funktoin
> + * vor dem ersten Aufruf einer anderen CDI-Funktion aufrufen.
>  * Initialisiert interne Datenstruktur der Implementierung fuer das jeweilige
>  * Betriebssystem und startet anschliessend alle Treiber.
>  *
> - * Ein wiederholter Aufruf bleibt ohne Effekt.
> + * Ein wiederholter Aufruf bleibt ohne Effekt. Es ist nicht definiert, ob diese
> + * Funktion zurückkehrt.
> + * \endgerman
> + *
> + * \english
> + * Drivers which implement their own main() function must call this function
> + * before they call any other CDI function. It initialises internal data
> + * structures of the CDI implementation and starts all drivers.
> + *
> + * This function takes effect only once, any other calls remain without effect.
> + * It is not defined if this function returns.
> + * \endenglish
>  */
>  void cdi_init(void);
For the english translation, I'd perhaps replace the last part with
something like this:
This function should only be called once, additional calls will have no effect.
Depending on the implementation, this function may or may not return.

Just a suggestion, of course. Aside from that, maybe look at using the
\<language> versions instead of \if <language>? If for no other reason
than consistency.

All in all, looks good to me.

Acked-by: Rich Edelman <redelman@xxxxxxxxx>