Re: [RFC PATCH 1/2] Docs/admin-guide/mm/damon/usage: mark scheme filters sysfs dir as deprecated

[sashiko-bot@kernel.org]

Sashiko AI review found 1 potential issue(s):
- [Low] Poor grammar and inappropriate terminology in the deprecation notice.
--

commit bd6da1d76d24f1b76f6957dd9993c899af48df43
Author: SeongJae Park <sj@kernel.org>

Docs/admin-guide/mm/damon/usage: mark scheme filters sysfs dir as deprecated

This commit updates the DAMON usage documentation to formally mark the
sysfs 'filters/' directory as deprecated. It recommends users migrate
to the 'core_filters/' and 'ops_filters/' directories instead.

> diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst
> index 534e1199cf091..4c222e956b100 100644
> --- a/Documentation/admin-guide/mm/damon/usage.rst
> +++ b/Documentation/admin-guide/mm/damon/usage.rst
[ ... ]
>  Use of ``filters`` directory can make expecting evaluation orders of given
> -filters with the files under directory bit confusing.  Users are hence
> -recommended to use ``core_filters`` and ``ops_filters`` directories.  The
> -``filters`` directory could be deprecated in future.
> +filters with the files under directory bit confusing.  For the reason,
> +``filters`` directory is deprecated.  It is still functioning, but it will be
> +broken and eventually removed in near future.  Users should use
> +``core_filters`` and ``ops_filters`` directories instead.

This isn't a bug, but could the phrasing here be smoothed out a bit? There
are a few awkward phrases like "make expecting evaluation orders" and "with
the files under directory bit confusing".

Also, stating that a sysfs interface "will be broken" is generally avoided
in kernel documentation. The standard convention is to say that an interface
is "deprecated and scheduled for removal" to avoid implying that userspace
will be intentionally broken.

Would a rewrite like this work better?

"Using the ``filters`` directory can make the evaluation order of filters
confusing. For this reason, the ``filters`` directory is deprecated. It
continues to function for now, but is scheduled for removal in the near
future."

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260421044928.141388-1-sj@kernel.org?part=1