Hi Tom, On Tue, 26 Nov 2024 at 08:55, Tom Rini <tr...@konsulko.com> wrote: > > 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.g...@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 <s...@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.
It depends what you mean by docs. U-Boot puts the documentation for exported functions in header files. Putting docs in C files clutters the docs with internal implementations, when most people just want to see the API. The way U-Boot does things, it is easy to see the internal (implementation) docs by looking at the C code and the external functions by looking at the header files. Regards, Simon
