From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751424AbcFWPiD (ORCPT ); Thu, 23 Jun 2016 11:38:03 -0400 Received: from mx0b-001b2d01.pphosted.com ([148.163.158.5]:51835 "EHLO mx0a-001b2d01.pphosted.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1750799AbcFWPiB (ORCPT ); Thu, 23 Jun 2016 11:38:01 -0400 X-IBM-Helo: d24dlp01.br.ibm.com X-IBM-MailFrom: bauerman@linux.vnet.ibm.com X-IBM-RcptTo: linux-kernel@vger.kernel.org From: Thiago Jung Bauermann To: Dave Young Cc: linuxppc-dev@lists.ozlabs.org, kexec@lists.infradead.org, linux-kernel@vger.kernel.org, Eric Biederman Subject: Re: [PATCH v3 3/9] kexec_file: Factor out kexec_locate_mem_hole from kexec_add_buffer. Date: Thu, 23 Jun 2016 12:37:49 -0300 User-Agent: KMail/4.14.3 (Linux/3.13.0-87-generic; KDE/4.14.13; x86_64; ; ) In-Reply-To: <2090497645.1524307.1466660647378.JavaMail.zimbra@redhat.com> References: <1466538521-31216-1-git-send-email-bauerman@linux.vnet.ibm.com> <20160623023052.GB12575@dhcp-128-11.nay.redhat.com> <2090497645.1524307.1466660647378.JavaMail.zimbra@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" X-TM-AS-MML: disable X-Content-Scanned: Fidelis XPS MAILER x-cbid: 16062315-0020-0000-0000-000002176B2E X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 16062315-0021-0000-0000-00002FEDF34E Message-Id: <4923900.bfxGnX6mM2@hactar> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:,, definitions=2016-06-23_07:,, signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 spamscore=0 suspectscore=0 malwarescore=0 phishscore=0 adultscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1604210000 definitions=main-1606230165 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Am Donnerstag, 23 Juni 2016, 01:44:07 schrieb Dave Young: > 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. > 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? 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: > 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. -- []'s Thiago Jung Bauermann IBM Linux Technology Center