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 (local)

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