On Tue, 2025-11-04 at 20:13 +0100, Thorsten Blum wrote: > On 4. Nov 2025, at 00:47, Huang, Kai wrote: > > It seems we don't have a consistent way of describing return values in the > > k-doc comments in sgx/main.c. E.g., > > > > /** > > * sgx_unmark_page_reclaimable() - Remove a page from the reclaim list > > > > ... > > > > * Return: > > * 0 on success, > > * -EBUSY if the page is in the process of being reclaimed > > */ > > > > > > /** > > * sgx_alloc_epc_page() - Allocate an EPC page > > > > ... > > > > * Return: > > * an EPC page, > > * -errno on error > > */ > > > > Perhaps we should make them consistent in format. > > > > But I think this can be done separately from fixing the typos. Maybe you > > can split out the typo fixing as a separate patch, and have another patch to > > fixing the return value description? > > I used the style mostly found in main.c and ioctl.c - would that be the > "correct" format for the others as well? Happy to submit a separate > patch if it's worth it.
I found a link documenting that (please search "Return values"): https://docs.kernel.org/doc-guide/kernel-doc.html In short, the doc suggested to use a "ReST list", e.g.,: * Return: * * %0 - OK to runtime suspend the device * * %-EBUSY - Device should not be runtime suspended But I am not a fan of cleaning up all the existing SGX comments to it, since this will just be a burden to maintainers I suppose. And I bet there are other places in the kernel not following this "ReST list", i.e., I view this as a suggestion but not a requirement. Another option is you can just change to follow the quoted two examples above (e.g., sgx_unmark_page_reclaimable()) so that at least in sgx/main.c they are consistent. Or just leave the comment as is. That's my 2cents, and in any way, I will be happy to review.
