On 25.09.17 07:25, Heinrich Schuchardt wrote:
On 09/25/2017 04:14 AM, Simon Glass wrote:
On 21 September 2017 at 10:30, Heinrich Schuchardt <xypron.g...@gmx.de> wrote:
Provide comments describing the boot service functions.

Signed-off-by: Heinrich Schuchardt <xypron.g...@gmx.de>
---
  lib/efi_loader/efi_boottime.c | 640 +++++++++++++++++++++++++++++++++++++++++-
  1 file changed, 638 insertions(+), 2 deletions(-)

Great to see this - but please can you put these comments in the
header file? That's the file that people read to see the API.

nit: efi_locate_protocol() needs a @return


Most of the functions are static.

@Alex
Where do you want the comments
- for boottime structure members

Not sure I understand. Where they're defined? :)

Basically always assume that 2 years from now someone who's never touched any efi_loader code touches it. What's the easiest way to ensure that he doesn't disconnect the documentation from the implementation and even creates new documentation :).

That said, please make sure that the code does stay readable enough despite the comments :).

- for non-static functions

Right above the function body itself

- for static functions with forward declaration?

Same here, wherever the function is actually implemented makes most sense IMHO. Not everyone in the U-Boot world uses an IDE and this way it's most obvious that changes need to get reflected in the documentation when the implementation changes.


Alex
_______________________________________________
U-Boot mailing list
U-Boot@lists.denx.de
https://lists.denx.de/listinfo/u-boot

Reply via email to