Re: [PATCH v2 1/4] mm/sparse: Clean up the obsolete code comment

Chao Fan
2019-03-26T09:37:39Z

On Tue, Mar 26, 2019 at 05:30:57PM +0800, Baoquan He wrote:
>On 03/26/19 at 10:23am, Michal Hocko wrote:
>> On Tue 26-03-19 17:02:24, Baoquan He wrote:
>> > The code comment above sparse_add_one_section() is obsolete and
>> > incorrect, clean it up and write new one.
>> >
>> > Signed-off-by: Baoquan He <bhe@redhat.com>
>>
>> Please note that you need /** to start a kernel doc. Other than that.
>
>I didn't find a template in coding-style.rst, and saw someone is using
>/*, others use /**. I will use '/**' instead. Thanks for telling.

How to format kernel-doc comments
---------------------------------

The opening comment mark ``/**`` is used for kernel-doc comments. The
``kernel-doc`` tool will extract comments marked this way. The rest of
the comment is formatted like a normal multi-line comment with a column
of asterisks on the left side, closing with ``*/`` on a line by itself.

See Documentation/doc-guide/kernel-doc.rst for more details.
Hope that can help you.

Thanks,
Chao Fan

>
>>
>> Acked-by: Michal Hocko <mhocko@suse.com>
>> > ---
>> > v1-v2:
>> > Add comments to explain what the returned value means for
>> > each error code.
>> >
>> > mm/sparse.c | 15 ++++++++++++---
>> > 1 file changed, 12 insertions(+), 3 deletions(-)
>> >
>> > diff --git a/mm/sparse.c b/mm/sparse.c
>> > index 69904aa6165b..b2111f996aa6 100644
>> > --- a/mm/sparse.c
>> > +++ b/mm/sparse.c
>> > @@ -685,9 +685,18 @@ static void free_map_bootmem(struct page *memmap)
>> > #endif /* CONFIG_SPARSEMEM_VMEMMAP */
>> >
>> > /*
>> > - * returns the number of sections whose mem_maps were properly
>> > - * set. If this is <=0, then that means that the passed-in
>> > - * map was not consumed and must be freed.
>> > + * sparse_add_one_section - add a memory section
>> > + * @nid: The node to add section on
>> > + * @start_pfn: start pfn of the memory range
>> > + * @altmap: device page map
>> > + *
>> > + * This is only intended for hotplug.
>> > + *
>> > + * Returns:
>> > + * 0 on success.
>> > + * Other error code on failure:
>> > + * - -EEXIST - section has been present.
>> > + * - -ENOMEM - out of memory.
>> > */
>> > int __meminit sparse_add_one_section(int nid, unsigned long start_pfn,
>> > struct vmem_altmap *altmap)
>> > --
>> > 2.17.2
>> >
>>
>> --
>> Michal Hocko
>> SUSE Labs
>
>