On Tue, Aug 15, 2023 at 04:39:16PM -0400, Peter Xu wrote: > On Tue, Aug 15, 2023 at 09:16:47PM +0100, Matthew Wilcox wrote: > > No, sometimes there are things which shouldn't be documented because they > > don't matter, and when changing code sometimes we forget to change the > > documentation, and then people read the documentation which is different > > from the code, and they get confused. > > > > It matters that the various 'private' members line up. It matters > > that folio->index matches page->index. It does not matter what > > offset _entire_mapcount is at. That can be moved around freely and no > > documentation needs to be changed. > > > > I don't want you to use FOLIO_MATCH to make any unnecessary assertions. > > The only assertion missing is for _private_1 and _private_2a, and that's > > why I wrote a patch to add them. > > I didn't mean to add assertions for _entire_mapcount (I don't even know > how..), but _mapcount and _refcount to clamp the fields, then all fields > can be clear, just like head/flags clamping the start of fields. Ah! mapcount does make sense, yes. We could just put a /* no more space here */ comment in, but an assert works too. > One thing I can understand that you'd like to avoid these "offset" things > is perhaps because you keep that in mind to, one day, have mmdesc replacing > folio so folio doesn't need to match struct page at all some day, > ideally. The order of fields, size of fields, etc. none of them should > matter, when it comes, and we should go toward that. However my argument > would be that, before that day comes IMHO we need some good documentation > for us to know how the fields look like now, why they worked, and how to > reuse new fields.. when that comes, we can just safely remove these > documentations. > > It's just that these 'offset's still matter and matters a lot now, imho, > but it's very confusing when read without some help. No, that's not why I'm opposed to them. I'm opposed to over-documenting things, as I just outlined. Documentation is necessary and good for all kinds of reasons, but it should be meaningful and not prone to rot. If there's a tool that can tell you something, there's no point in documenting it; that's why I pointed you towards pahole. I also like "documentation" which is checked by the compiler, hence the existence of the FOLIO_MATCH macro which documents that the two structures line up, and the compiler checks that they do. FOLIO_MATCH even caught a bug! > Let me try one more time to see how you think about it on an rfcv3. If > that still doesn't get any form of ack from you, I'll put this aside. At least we've got to something that I like the idea of ;-)
