On Thu, Jun 18, 2020 at 12:14:00PM +0000, Johannes Thumshirn wrote: > On 18/06/2020 14:00, Qu Wenruo wrote: > > > > > > On 2020/6/18 下午7:57, Johannes Thumshirn wrote: > >> On 18/06/2020 09:50, Qu Wenruo wrote: > >>> These two functions have extra conditions that their callers need to > >>> meet, and some not-that-common parameters used for return value. > >>> > >>> So adding some comments may save reviewers some time. > >> > >> These comments have a style/formatting similar to kerneldoc, can you make > >> them real kerneldoc? > > > > Mind to give an example? It must be a coincident to match some existing > > format. > > > > Sure: > > /** > * check_can_nocow() - Check if we can write into [@offset, @offset + @len) of @inode. > * > * @offset: File offset > * @len: The length to write, will be updated to the nocow writable > * range > * @orig_start: Return the original file offset of the file extent (Optional) > * @orig_len: Return the original on-disk length of the file extent (Optional) > * @ram_bytes: Return the ram_bytes of the file extent (Optional) > * > * Return: >0 and update @len if we can do nocow write into [@offset, @offset + @len), > * 0 if we can't do nocow write or <0 if error happened. > * > * NOTE: This only checks the file extents, caller is responsible to wait for > * any ordered extents. > * > */ > > See also Documentation/doc-guide/kernel-doc.rst for a detailed description The kernel doc is relatively good, but for our internal helpers I see much point using it and keep the function comment style more relaxed. The short summary, argument description, long description and return values. No strict formatting of the parameters but the "@name: text" looks ok.
