linux-kernel - Re: [PATCH] docs: Integrate rustdoc into Rust documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Thu, 1 Dec 2022 14:40:33 -0600
From:   Carlos Bilbao <carlos.bilbao@....com>
To:     Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
Cc:     corbet@....net, ojeda@...nel.org, bilbao@...edu,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        konstantin@...uxfoundation.org, Akira Yokosawa <akiyks@...il.com>
Subject: Re: [PATCH] docs: Integrate rustdoc into Rust documentation

On 12/1/22 06:42, Miguel Ojeda wrote:

> On Wed, Nov 30, 2022 at 11:08 PM Carlos Bilbao <carlos.bilbao@....com> wrote:
>
>> +ifdef CONFIG_RUST
>> +       @make LLVM=1 rustdoc
>> +endif
> The Rust docs should probably be built with the build
> system/config/... as given, whether it is GCC, LLVM, etc. This should
> probably use `$(MAKE)` too; and if you intended to remove the command
> line definitions, `MAKEOVERRIDES` too.


Sounds good.


> By the way, while checking this, I noticed we use some `CONFIG_`s in
> this `Makefile`, but we do not perform a config sync for the `*docs`
> targets, so one needs to do so manually, i.e. it can be a pitfall for
> e.g. `CONFIG_WARN_MISSING_DOCUMENTS` and ` as well as a potential
> `CONFIG_RUST`. Should this be fixed orthogonally, or is it intended?
> (some targets do not need the sync, and the ones that need are
> probably less used, so I guess that could be the reason?).


I don't understand config sync. Perhaps that, e.g. Documentation/Makefile
checks for broken docs, for CONFIG_WARN_MISSING_DOCUMENTS, but we don't
do that for rust/Makefile? I'm not sure, but it does sound orthogonal, yes.


>
>> +Rustdoc output
>> +==============
>> +
>> +If this documentation includes rustdoc-generated HTML, the entry point
>> +can be found `here. <rustdoc/kernel/index.html>`_
> Perhaps this sentence could be moved to the top of the index file, so
> that users do not need two clicks when visiting "Rust"? That way we
> avoid one more file too.


Yes, that will be better :)


>
>> +RUSTDOC_OUTPUT=$(objtree)/Documentation/output/rust/rustdoc
> Please add a space around the equal sign to be consistent with (most)
> of the rest of the file.


Ack


>
> Cheers,
> Miguel


Thanks,
Carlos