lrs-lang/doc

The lrs documentation generator

doc's Issues

doc comments don't work in macros

Consider the following code from lrs:

create_flags! {
    #[doc = "Return an error instead of blocking.\n"]
    #[doc = "= See also"]
    #[doc = "* link:man:tee(2) and SPLICE_F_NONBLOCK therein"]
    flag TEE_DONT_BLOCK = SPLICE_F_NONBLOCK;
}

We are using #[doc because using /// doesn't work properly. If we used the /// version, the slashes would also show up in the documentation itself and completely mess up our output.

Rewrite the html generator

The generator is absolute garbage that is full of copy-pasted code everywhere.

Improve rustdoc performance

The rustdoc performance in json mode is abysmal. If I recall correctly, rustdoc takes 6 seconds to generate the lrs json.

Luckily, there is one simple trick that can be applied to rustdoc to get this number down to 0.5 seconds (iirc). We should upstream this change at some point.

Primitives aren't linked and don't have pages

i8, &[T], etc. should be link to something.

Pages with the same name overwrite each other

I think this is a language bug. Two things should never have the same name at the same level.

Implement a search

Gonna have to use javascript for that. RIP links support.

Make lrs_doc usable for other crates

Currently, lrs is hardcoded in some places.

Don't show () return types.

Sometimes we see the following:

fn f() -> ()

This shouldn't happen.

Typedefs cannot be documented because of rustc issues

In particular, Vec<T, Heap> is always shown as Vec<T, Libc> which is absolutely wrong. Furthermore, their documentation is not even stored anywhere in the rlib.

Trait page output is not fully implemented

In particular, we can't see which types implement a given trait.

Reexports with as are not documented correctly

mem::cast is currently documented as mem::transmute.

Don't show default arguments

Currently, Result is written as

Result<(), Errno>

Those default arguments should never be shown. This includes the following case:

Result<T, Errno>

which should be written like this:

Result<T>

Static trait methods are shown in the methods section

In particular, there is an empty Receiver column. They should get their own section.