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.
