[U-Boot] [PATCH 1/1] efi_loader: provide function comments for boot services

[Alexander Graf]

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.glpk at gmx.de> wrote:
>>> Provide comments describing the boot service functions.
>>>
>>> Signed-off-by: Heinrich Schuchardt <xypron.glpk at 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