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@xxxxxxxxxxxxx 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
