On Mon, 29 Jul 2019 14:53:45 -0700, Jonathan Lemon wrote:

On 29 Jul 2019, at 14:25, Jakub Kicinski wrote:

quoted

On Mon, 29 Jul 2019 14:22:11 -0700, Jakub Kicinski wrote:  

quoted

quoted

quoted

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.