On Tue, Jul 20, 2021 at 01:40:05PM +0300, Mike Rapoport wrote: > > +/** > > + * 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? > > > + * @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.
