Re: [PATCH V1 for-next 1/9] IB/core: Introduce peer client interface

[Bart Van Assche <bvanassche-HInyCGIudOg@public.gmane.org>]

On 10/12/14 14:03, Shachar Raindel wrote:
>> The kernel-doc output for the above comment block is incomplete. Please
>> fix this, and please also fix the warnings reported by the kernel-doc
>
> We are not sure what is the best way to document an operations struct
> using nanodocs.
> Looking at mmu_notifiers, they are documented inline, using a
> comment style that nanodoc can't parse
> (http://lxr.free-electrons.com/source/include/linux/mmu_notifier.h#L27 )
> Looking at the file_operations struct, there is no documentation
> whatsoever
> (http://lxr.free-electrons.com/source/include/linux/fs.h#L1482 )
> Looking at ib_device
> (http://lxr.free-electrons.com/source/include/rdma/ib_verbs.h#L1436 ),
> again there is no documentation.
>
> I attach our current nanodoc parsable comment. No errors are now
> generated when running kernel-doc on the attached file.
> Is this what you are aiming at? Can you give an example for the proper
> way to format such comments?

Hello Sachar,

Please note that I'm not an expert with regard to kernel documentation 
formats. In my opinion the documentation in the attached header file is 
not only easy to read for humans but the scripts/kernel-doc tool also 
generates nicely formatted HTML documentation from that document so I'm 
happy with the documentation format that is used in that header file.

Bart.

--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html