Re: [lwip-devel] [PATCHv6 03/14] net/lwip: implement dns cmd

[Ilias Apalodimas]

On Wed, 16 Aug 2023 at 14:01, Maxim Uvarov <maxim.uvarov@linaro.org> wrote:
>
>
>
> On Wed, 16 Aug 2023 at 16:26, Ilias Apalodimas <ilias.apalodimas@linaro.org> 
> wrote:
>>
>> On Tue, 15 Aug 2023 at 17:42, Tom Rini <trini@konsulko.com> wrote:
>> >
>> > On Tue, Aug 15, 2023 at 06:42:14PM +0600, Maxim Uvarov wrote:
>> > > On Mon, 14 Aug 2023 at 20:19, Ilias Apalodimas 
>> > > <ilias.apalodimas@linaro.org>
>> > > wrote:
>> > >
>> > > [...]
>> > >
>> > >
>> > > > > +/*
>> > > > > +* This function creates the DNS request to resolve a domain host 
>> > > > > name.
>> > > > Function
>> > > >
>> > > > You need the name of the function as well.  Please have a look at how 
>> > > > the
>> > > > rest of the code is documented.
>> > > >
>> > > > > +* can return immediately if previous request was cached or it might
>> > > > require
>> > > > > +* entering the polling loop for a request to a remote server.
>> > > > > +*
>> > > > > +* @name  dns name to resolve
>> > > >
>> > > > @name: etc
>> > > >
>> > > > > +* @varname (optional) U-Boot variable name to store the result
>> > > > > +* Return: ERR_OK(0) for fetching entry from the cache
>> > > > > +*         ERR_INPROGRESS(-5) success, can go to the polling loop
>> > > > > +*         Other value < 0, if error
>> > > > > +*/
>> > > > >
>> > > >
>> > >
>> > > Is there any command to check all the files for the comments style?
>> >
>> > I suspect if you included them in docs, htmldocs/etc would note
>> > problems, Heinrich?
>> >
>>
>> Yes 'make htmldocs' blows up on errors, at least for the EFI subsystem
>>
>> Cheers
>> /Ilias
>
>
> O! Ilias thanks for the reference. First patch for doc/develop/net_lwip.rst 
> needed direct references:
>
> .. kernel-doc:: include/net/lwip.h
>    :internal:
>
> to force Sphinx  to generate docs for these files. (as I understand for .c 
> files it does checks and for .h files it generates docs).
>
> Without specification syntax is not validated. It will be good to do 
> something to check all U-Boot .h files for the common syntax later.

You need comments that look like this
  /**
   * parse_event_log_header() -  Parse and verify the event log header
fields
   *
   * @buffer:                     Pointer to the start of the eventlog
   * @size:                       Size of the eventlog
   * @pos:                        Return offset of the next event in
buffer right
   *                              after the event header i.e specID
   *
   * Return:      status code
   */

Cheers
/Ilias
>
> BR,
> Maxim.
>
>
>
>>
>> > --
>> > Tom