On Wed, Jul 21, 2021 at 04:42:36AM +0100, Matthew Wilcox wrote:

On Tue, Jul 20, 2021 at 01:40:05PM +0300, Mike Rapoport wrote:

quoted

quoted

+/**
+ * folio_shift - The number of bits covered by this folio.

For me this sounds like the size of the folio in bits.
Maybe just repeat "The base-2 logarithm of the size of this folio" here and
in return description?

quoted

+ * @folio: The folio.
+ *
+ * A folio contains a number of bytes which is a power-of-two in size.
+ * This function tells you which power-of-two the folio is.
+ *
+ * Context: The caller should have a reference on the folio to prevent
+ * it from being split.  It is not necessary for the folio to be locked.
+ * Return: The base-2 logarithm of the size of this folio.
+ */

I've gone with:

 /**
- * folio_shift - The number of bits covered by this folio.
+ * folio_shift - The size of the memory described by this folio.
  * @folio: The folio.
  *
- * A folio contains a number of bytes which is a power-of-two in size.
- * This function tells you which power-of-two the folio is.
+ * A folio represents a number of bytes which is a power-of-two in size.
+ * This function tells you which power-of-two the folio is.  See also
+ * folio_size() and folio_order().
  *
  * Context: The caller should have a reference on the folio to prevent
  * it from being split.  It is not necessary for the folio to be locked.

I like it. :)

--D