On 06/23/16 at 12:37pm, Thiago Jung Bauermann wrote:

Am Donnerstag, 23 Juni 2016, 01:44:07 schrieb Dave Young:

quoted

Hmm, hold on. For declaring a struct in a header file, comment should be
just after each fields, like below, your format is for a function instead:
struct pci_slot {
        struct pci_bus *bus;            /* The bus this slot is on */
        struct list_head list;          /* node in list of slots on this
bus */ struct hotplug_slot *hotplug;   /* Hotplug info (migrate over
time) */ unsigned char number;           /* PCI_SLOT(pci_dev->devfn) */
struct kobject kobj;
};

The comment style you mention above is not extractable documentation. The 
style I used is what is described in section "kernel-doc for structs, 
unions, enums, and typedefs" in Documentation/kernel-doc-nano-HOWTO.txt.

You are right and I was wrong!

quoted

BTW, what is @size? there's no size field in kexec_buf. I think it is not
necessary to add these comment, they are easy to understand. If you really
want, please rewrite them correctly, for example "image" description is
wrong. It is not only for searching memory only, top_down description is
also bad.

Sorry, I moved these comments from kexec_locate_mem_hole but forgot to 
rename the parameters to what they are called in struct kexec_buf. @size 
should have been @memsz (other fields also have wrong names, I'll fix them 
as well). The image description is correct in the context of where struct 
kexec_buf is used and explains what it will be used for in the function 
taking kexec_buf as an argument. It is not meant as a general description of 
the purpose of struct kimage. What is bad about the description of top_down?

It is not clear enough to me, I personally think the original one in
source code is better:
/* allocate from top of memory hole */

I decided to add these comments because struct kexec_buf is now part of the 
kernel API for kexec. kernel-doc-nano-HOWTO.txt says:

quoted

We definitely need kernel-doc formatted documentation for functions
that are exported to loadable modules using EXPORT_SYMBOL.

We also look to provide kernel-doc formatted documentation for
functions externally visible to other kernel files (not marked
"static").

We also recommend providing kernel-doc formatted documentation
for private (file "static") routines, for consistency of kernel
source code layout.  But this is lower priority and at the
discretion of the MAINTAINER of that kernel source file.

If you think they are not necessary or just add clutter I can leave them 
out.

I'm fine with either way.

THanks
Dave