On Tue, Feb 04, 2020 at 08:39:19PM +0800, Qu Wenruo wrote: > >> Although I'm not sure if such lifespan should belong to delalloc-space.c. > > > > This omits a lot of critical details. FOr example it should be noted > > that in btrfs_buffered_write we reserve as much space as is requested by > > the user. Then in run_delalloc_range it must be mentioned that in case > > of compressed extents it can be called to allocate an extent which is > > less than the space reserved in btrfs_buffered_write => that's where the > > possible space savings in case of compressed come from. > > If you spoiler everything in the introduction, I guess it's no longer > introduction. > An introduction should only tell the overall picture, not every details. > For details, we go read mentioned functions. > > And too many details would make the introduction pretty hard to > maintain. What if one day we don't the current always reserve behavior > for buffered write? > > So I tend to have just a overview, and entrance function. With minimal > details unless it's a really complex design. I'd rather keep it as it is and enhance more, the ascii graphics might help but I don't insist. Even if it's introductory, giving just pointers would be IMHO too little. I'm assuming the overview should be enough to read and then go to code and already have a clue what's happening. We can update the docs further but we need a start so I've applied v2 to misc-next and let's take that as starting point so we can discuss suggested improvements as new patches. In case there's something that really does not fit the .c file comment there's always the docs git repository.
