Re: [PATCH] docs: printk-basics: update the pr_debug() kerneldoc

["Ricardo Cañuelo" <ricardo.canuelo@collabora.com>]

Hi Petr, thanks for taking the time to review this

On Tue, 2020-05-19 at 15:15 +0200, Petr Mladek wrote:
> It is pity that you did not add other printk maintainers into CC for
> the patches adding this documentation and comments. I was sick
> last two months and was not able to check mails.

I'm sorry for that and I hope you're better now.

> Adding them now. Note that the following patch is already in
> linux-next, see
> https://lore.kernel.org/r/20200403093617.18003-1-ricardo.canuelo@collabora.com

Indeed, I mentioned that in the patch. Maybe I should've been clearer in the
background description.

> Well, I have mixed feelings about this type of documentation. It might explain
> some things that are less obvious, for example, the meaning of
> pr_fmt(). On the other hand:
> 
>   + It might be complicated to keep it in sync.
> 
>   + I wonder how many developers would actually read it.
> 
>   + The doc comments in include/linux/prinkt.h are really
>     long and describe obvious things.
> 
> By other words. These comments make the headers and sources hard to
> read. And at least in this particular case, the gain is questionable.

Well, I think that some things may not be too obvious for beginners and that
documenting them explicitly is a positive thing overall. I don't think this kind
of comments (comment blocks before a function prototype, not interleaved in the
code) pollute the code or make it harder to read, but that's a personal opinion,
I guess.

I agree that this might introduce a maintainance overhead when it comes to
sync'ing the code and the documentation but, on the other hand, printk.h isn't
something that changes too frequently, is it?

Best regards,
Ricardo