Yueh-Shun Li <shamrocklee@xxxxxxxxxx> writes: >> So everything we add to our documentation has a cost in terms of reader >> attention. We ask people to read through a lot of material now, and >> should only increase that ask for good reason. >> >> With that context, I have to wonder whether we really need to tell our >> readers, who are supposed to be capable developers, that reuse can help >> to avoid name collisions? >> > > The motivation comes from existing inconsistency of the "__stringify()" > macro > definition between e.g. "samples/bpf/tracex5.bpf.c" and other files. > > I agree that increasing the length of the documentation without > substantial benefits would not be helpful for the readers, and > doubling the length of a section is too much for its purpose. > > Should I shorten it into one sentence, like > > ``` > On the other hand, locally-defined variants, such as ``#define > __stringify(x) #x``, > could lead to naming collisions that break otherwise functioning > facilities. > ``` > > or just omit it in the next version of patches? My own feeling (others may well disagree) is that this isn't worth mentioning in the coding-style document. What you *could* do is to fix the redefinitions (if that hasn't happened yet) and make sure that the macros in question are covered in our kernel documentation. Thanks, jon