If a reexport comes from a non-public module, then the documentation for the
reexport will be inlined into the module that exports it, but if the reexport is
targeted at a public type (like the prelude), then it is not inlined but rather
hyperlinked.
This adds support for the `--test` flag to rustdoc which will parse a crate,
extract all code examples in doc comments, and then run each test in the
extra::test driver.
Now that the metadata is an owned value with a lifetime of a borrowed byte
slice, it's possible to have future optimizations where the metadata doesn't
need to be copied around (very expensive operation).
Now that the metadata is an owned value with a lifetime of a borrowed byte
slice, it's possible to have future optimizations where the metadata doesn't
need to be copied around (very expensive operation).
Beforehand the id of a method was the id of the 'self' argument, but this is not
the id which privacy was using (the id of the ast::method) struct, so by moving
the ids over to the privacy-target ones the methods are now stripped correctly.
Previously an ExprLit was created *per byte* causing a huge increase in memory
bloat. This adds a new `lit_binary` to contain a literal of binary data, which
is currently only used by the include_bin! syntax extension. This massively
speeds up compilation times of the shootout-k-nucleotide-pipes test
before:
time: 469s
memory: 6GB
assertion failure in LLVM (section too large)
after:
time: 2.50s
memory: 124MB
Closes#2598
For the benefit of the pretty printer we want to keep track of how
string literals in the ast were originally represented in the source
code.
This commit changes parser functions so they don't extract strings from
the token stream without at least also returning what style of string
literal it was. This is stored in the resulting ast node for string
literals, obviously, for the package id in `extern mod = r"package id"`
view items, for the inline asm in `asm!()` invocations.
For `asm!()`'s other arguments or for `extern "Rust" fn()` items, I just
the style of string, because it seemed disproportionally cumbersome to
thread that information through the string processing that happens with
those string literals, given the limited advantage raw string literals
would provide in these positions.
The other syntax extensions don't seem to store passed string literals
in the ast, so they also discard the style of strings they parse.
The general idea of hyperlinking between crates is that it should require as
little configuration as possible, if any at all. In this vein, there are two
separate ways to generate hyperlinks between crates:
1. When you're generating documentation for a crate 'foo' into folder 'doc',
then if foo's external crate dependencies already have documented in the
folder 'doc', then hyperlinks will be generated. This will work because all
documentation is in the same folder, allowing links to work seamlessly both
on the web and on the local filesystem browser.
The rationale for this use case is a package with multiple libraries/crates
that all want to link to one another, and you don't want to have to deal with
going to the web. In theory this could be extended to have a RUST_PATH-style
searching situtation, but I'm not sure that it would work seamlessly on the
web as it does on the local filesystem, so I'm not attempting to explore this
case in this pull request. I believe to fully realize this potential rustdoc
would have to be acting as a server instead of a static site generator.
2. One of foo's external dependencies has a #[doc(html_root_url = "...")]
attribute. This means that all hyperlinks to the dependency will be rooted at
this url.
This use case encompasses all packages using libstd/libextra. These two
crates now have this attribute encoded (currently at the /doc/master url) and
will be read by anything which has a dependency on libstd/libextra. This
should also work for arbitrary crates in the wild that have online
documentation. I don't like how the version is hard-wired into the url, but I
think that this may be a case-by-case thing which doesn't end up being too
bad in the long run.
Closes#9539
They're getting smaller each time though!
The highlight of this round is source files in documentation. Still trying to figure out the best syntax-highlighting solution.
This removes the internal type representation of an `External` type and instead
relies on passing around DefId structures and interpreting them accordingly.
Progress on #9539, but there's still the problem of a crate => url mapping.
All items have source links back to their actual code. Source files can be
omitted with the doc(html_no_source) attribute on the crate. Currently there is
no syntax highlighting, but that will come with syntax highlighting with all
other snippets.
Closes#2072
This slurps up everything inside of an 'extern' block into the enclosing module
in order to document them. The documentation must be on the items themselves,
and they'll show up next to everything else on the module index pages.
Closes#5953
This will probably need to get tweaked once the privacy rules have been fully
agreed on, but for now this has all of the infrastructure necessary for
filtering out private items.
Closes#9410
