Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
MIME-Version: 1.0
References: <cover.1549540487.git.efremov@ispras.ru> <CAGXu5jJ8DaoXk4Vt-K_Tgvpe4=wgHZ3Z1Y=D8JzRHU9n=bvgtA@mail.gmail.com>
 <67ff280b6867b9a594ee16b2ad83bb7f@ispras.ru>
In-Reply-To: <67ff280b6867b9a594ee16b2ad83bb7f@ispras.ru>
From:   Kees Cook <keescook@chromium.org>
Date:   Sun, 17 Feb 2019 14:15:45 -0800
Message-ID: <CAGXu5j+VMU3LT77KkyoAwuVAemfM0mayvBcy3Y0K_a7UDBL=ow@mail.gmail.com>
Subject: Re: [PATCH 00/10] LSM documentation update
To:     efremov <efremov@ispras.ru>
Cc:     linux-security-module <linux-security-module@vger.kernel.org>,
        Casey Schaufler <casey@schaufler-ca.com>,
        "Eric W. Biederman" <ebiederm@xmission.com>,
        Eric Paris <eparis@parisplace.org>,
        John Johansen <john.johansen@canonical.com>,
        James Morris <jmorris@namei.org>,
        "Serge E. Hallyn" <serge@hallyn.com>,
        Paul Moore <paul@paul-moore.com>,
        Kentaro Takeda <takedakn@nttdata.co.jp>,
        LKML <linux-kernel@vger.kernel.org>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Sun, Feb 17, 2019 at 10:04 AM efremov <efremov@ispras.ru> wrote:
>
> Kees Cook =D0=BF=D0=B8=D1=81=D0=B0=D0=BB 2019-02-11 22:28:
> > On Thu, Feb 7, 2019 at 4:45 AM Denis Efremov <efremov@ispras.ru> wrote:
> >>
> >> Recent "New LSM Hooks" discussion has led me to the
> >> thought that it might be a good idea to slightly
> >> update the current documentation. The patchset adds
> >> nothing new to the documentation, only fixes the old
> >> description of hooks to reflect their current state.
>
> >
> > Do these fixes silence any warnings during the documentation build?
> > (i.e. how did you verify the results beyond eyeballing the changes)
> >
> > -Kees
>
> This LSM documentation is not used during the documentation build.
> At least I can't find it in the resulting build directory and at
> the online documentation on the kernel. Most of the fixes are pretty
> obvious and can be checked by comparing an lsm hook declaration and
> its description in the LSM comment from lsm_hooks.h I tried to be
> exhaustive in the commits description and in every case to reference
> the original commit where the interface was changed without
> documentation update.

I'll send an official patch that'll hook this up. I've been meaning to
do it for a while, but there were several things that needed cleaning
up (and you've snagged most of them). So with this patch, you'll be
able to check the output for "make htmldocs" for lsm_hooks.h errors:

diff --git a/Documentation/security/LSM.rst b/Documentation/security/LSM.rs=
t
index 8b9ee597e9d0..31d92bc5fdd2 100644
--- a/Documentation/security/LSM.rst
+++ b/Documentation/security/LSM.rst
@@ -11,4 +11,7 @@ that end users and distros can make a more informed
decision about which
 LSMs suit their requirements.

 For extensive documentation on the available LSM hook interfaces, please
-see ``include/linux/lsm_hooks.h``.
+see ``include/linux/lsm_hooks.h`` and associated structures:
+
+.. kernel-doc:: include/linux/lsm_hooks.h
+   :internal:


--=20
Kees Cook