Re: [PATCH 1/3 net-next] linux: Add skb_frag_t page_offset accessors

[Jakub Kicinski <jakub.kicinski@netronome.com>]

On Mon, 29 Jul 2019 14:53:45 -0700, Jonathan Lemon wrote:
> On 29 Jul 2019, at 14:25, Jakub Kicinski wrote:
> 
> > On Mon, 29 Jul 2019 14:22:11 -0700, Jakub Kicinski wrote:  
> >>>> I realize you're following the existing code, but should we perhaps
> >>>> use
> >>>> the latest kdoc syntax? '()' after function name, and args should have
> >>>> '@' prefix, '%' would be for constants.  
> >>>
> >>> That would be a task for a different cleanup.  Not that I disagree with
> >>> you, but there's also nothing worse than mixing styles in the same file.  
> >>
> >> Funny you should say that given that (a) I'm commenting on the new code
> >> you're adding, and (b) you did do an unrelated spelling fix above ;)  
> >
> > Ah, sorry I misread your comment there.
> >
> > Some code already uses '()' in this file, as for the '%' skb_frag_
> > functions are the only one which have this mistake, the rest of kdoc
> > is correct.  
> 
> The kernel-doc.rst guide seems to indicate that function names should
> have () at the end - but none of them do so within this file.  (only when
> talking about the function in the document).

/**
 * skb_complete_tx_timestamp() - deliver cloned skb with tx timestamps

/**
 * skb_tx_timestamp() - Driver hook for transmit timestamping

> The %CONST indicates name of a constant - I'm unclear whether this is
> supposed to refer to a constant parameter.  For example:
> 
> /**
>  *      __skb_peek - peek at the head of a non-empty &sk_buff_head
>  *      @list_: list to peek at
>  *
>  *      Like skb_peek(), but the caller knows that the list is not empty.
>  */
> static inline struct sk_buff *__skb_peek(const struct sk_buff_head *list_)
> {
>         return list_->next;
> }

Hmm.. I'm not sure I follow, this example does not use %, but & which
is for types. Quoting from:

https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#highlights-and-cross-references

@parameter
    Name of a function parameter. (No cross-referencing, just formatting.)
%CONST
    Name of a constant. (No cross-referencing, just formatting.)


So in your case you should use @delta, rather than %delta.