[LinuxPPS] task force was I'm still here! :)

[Rodolfo Giometti]

On Sun, Jan 25, 2009 at 09:18:27AM +0100, Udo van den Heuvel wrote:
> Heiko Gerstung wrote:
> >>> 1. Rewrite the in-line documentation to the kernel standards.  Make 
> >>> sure these are not flagged in anyway by checkpatch.pl.  Doc change - 
> >>> possible non-programmer task.
> 
> > Here is what Hal posted from Alans comments:
> > 
> >> linuxpps-core-support.patch
> > 
> >>
> >> looks generally good, but the comments should get a little loving.
> 
> So the functions need new comments? (see down)
> 
> >> Please remove the stupid filenames that always get out of sync in
> >> the top of file comments,
> 
> I.e.:
> 
> +/*
> + * timepps.h -- PPS API main header
> + *
> + * Copyright (C) 2005-2007   Rodolfo Giometti <giometti at linux.it>
> + *
> + *   This program is free software; you can redistribute it and/or modify
> 
> becomes
> 
> 
> +/*
> + * PPS API main header
> + *
> + * Copyright (C) 2005-2007   Rodolfo Giometti <giometti at linux.it>
> + *
> + *   This program is free software; you can redistribute it and/or modify
> 
> ?

Yes.

>   and make the documentation of exported
> >> symbols kernel-doc instead of it's weird own format.
> 
> This is about sysfs-pps?

See file Documentation/kernel-doc-nano-HOWTO.txt.

> > 
> > I guess he means that there should be a little bit more comments and the 
> > ones that are there should be expanded a little bit.
> 
> One example for me to understand better, I started with timepps.h
> 
> 
> /**
>   * time_pps_create() - create pps source
>   * @arg1:       source
>   * @arg2:       handle
>   *
>   * Creates pps source from device passed in handle
>   *
>   **/
> 
> static __inline int time_pps_create(int source, pps_handle_t *handle)
> 
> Is this anything like it should be?

Documentation should be something like:

/**
 * struct blah - the basic blah structure
 * @mem1:       describe the first member of struct blah
 * @mem2:       describe the second member of struct blah,
 *              perhaps with more lines and words.
 *
 * Longer description of this structure.
 **/

Currently describing only exported symbols should be enought...

Please provide __one__ patch for each logical modifications: i.e. one
patch for documentation fixup and one patch for stripping out the
filenames. Also, please, be sure checkpatch has nothing to say about
your patch. :)

Thanks,

Rodolfo

-- 

GNU/Linux Solutions                  e-mail: giometti at enneenne.com
Linux Device Driver                          giometti at linux.it
Embedded Systems                     phone:  +39 349 2432127
UNIX programming                     skype:  rodolfo.giometti