[PATCH 05/13] efi_loader: Move some memory-function comments to header

[Tom Rini]

On Tue, Nov 26, 2024 at 08:37:33AM -0700, Simon Glass wrote:
> Hi Heinrich,
> 
> On Tue, 26 Nov 2024 at 02:35, Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:
> >
> > On 25.11.24 21:44, Simon Glass wrote:
> > > Exported functions should be documented in the header file, not the
> > > implementation. We tend to make such updates on a piecemeal basis to
> > > avoid a 'flag day'. Move some comments related to memory allocation to
> > > follow the convention.
> > >
> > > Signed-off-by: Simon Glass <sjg at chromium.org>
> >
> > Please, have a look at this line in doc/
> >
> > doc/api/efi.rst:78:
> > .. kernel-doc:: lib/efi_loader/efi_memory.c
> 
> Hmm, we should not add C files as then we end up with all sorts of
> internal functions, like checksum(). The help is a bit of a mess on
> that page IMO and it could use an index at the top or side.

Why? Looking at the linux kernel (where we borrow this framework from
and lots of developers expect to follow that style) it's extremely
common to kernel-doc C files. I don't see why documenting internal
functions (which should be clear as being internal) is a problem.

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 659 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20241126/c9e3e82b/attachment.sig>