►
Description
RustConf 2018 - The Dark Secrets Lurking Inside cargo doc by Quiet Misdreavus
Every Rustacean reads the standard library docs (or some other library docs) sooner or later. Many Rustaceans have run cargo doc to generate some documentation for their own library or their dependencies. But how many have looked at the tool behind cargo doc? In this talk, I'll divulge some hidden secrets of rustdoc, the tool used by cargo doc to generate documentation.
A
A
So
this
is
basically
the
output
of
a
dog.
It's
consistent
on,
like
every
library
that
you're
gonna
look
at
unless
they
do
like
have
their
own
little
guys.
I'll
have
to
decide
so
like
it's
gonna,
look
very
much
the
same
for
a
lot
of
places,
and
so,
like
kind
of
getting
into
a
few
place
special
things,
you
can
do
with
it
a
lot
of
the
like
handwritten
box.
A
And
there
is
not
only
just
like
the
hand,
written
prose
but
also
awake.
The
type
declaration
is
everything
that
goes
into
a
training
bowl
will
just
like
really
condense.
These
methods
there
are
these
traits
to
chase
another
really
powerful
thing
that
Russ
talk.
Does
that
is
really
cool?
Is
that
it
packages
the
source.
A
Good
is
this
button
for
that
on
the
crate
root,
you
can
say,
see
olive
here's,
y'all
studs
items
and
you
click
it,
and
it's
just
this
big
ol
list.
The
page
is
actually
really
huge
where
you
have
absolutely
everything
by
name
you
can
say
well,
I
remembered
this
thing
was
called
split
or
something,
and
you
can
control
that
for
it.
If
you
don't
want
to
use
the
JavaScript
search
in
there.
Speaking
of
if
you
look
for
a
type
in
the
JavaScript
search
in
the
little
search
bar
at
the
top
of
the
docs
there's.
A
Sometimes.
But
here's
like
just
like
a
handful
of
things,
there's
keyboard
shortcuts
that
you
can
use.
There's
like
settings
to
automatically
fold
or
unfold
things
and
like
there,
you
can
search
for
the
operator
symbols
of
traits
that
correspond
to
those
operators,
and
you
can
go
straight
to
those
traits
without
having
to
remember
what
was
the
thing.
What's
the
name
of
the
trait
that
you
use
with
star?
Well,
they
here
its
mole
and
DRF.
A
So
I've
tried
to
be
cagey
with
it,
but
when
you
run
cargo
dock,
much
like
when
it
compiles
your
code
with
cargo,
build
or
cargo
run
cargo,
just
kind
of
like
shells
out
another
tool
that
comes
with
the
rest
distribution,
that
tool
is
called
Russ
stock.
So
much
like
when
you
run
cover
bill
that
actually
like
builds
up
command
to
rust,
see
the
compiler.
When
you
run
cargo
dock,
it
builds
up
a
command
to
Russ
dock
so
that
it
can
create
your
documentation
out
and
so
to
kind
of
introduce
the
next
feature.
A
One
of
the
really
powerful
features
I
think
this
hardly
counts
as
obscure.
The
really
powerful
features
that
Russ
stock
has.
Is
that
you
can?
If
you
write
a
code
sample
in
your
dogs,
it's
it
will
treat
that
as
a
test.
So
if
you're
on
cargo
test
or
if
you
limit
it
with
cargo
tests
doc,
it
Russ
stock
will
scan
your
documentation
peel
out.
All
of
the
all
of
the
code,
samples
that
you've
written
in
and
try
to
compile
it
with
your
crate
to
make
sure
that
you
don't
have
code
in
your
docks.
A
That
goes
stale,
and
so
it's
really
really
helpful
to
have
like
these
examples
actually
work
and
if
you're
running
tests,
then
you
know
you
can
actually
verify
that.
Yes,
my
Doc's
actually
show
you
code
that
works,
so
it's
worth
kind
of
digging
into
what
Russ
doc
does
when
it
has
your
dog
test.
So
in
the
sample
there
I
had
this
two
line:
thing
that
just
instantiated
this
empty
struct,
some
struct
and
then
had
a
print
line,
and
so
what
once?
A
What
Rostock
wants
to
do
is
that
it
wants
to
take
that
code,
snippet,
that
you
gave
it
and
turn
it
into
an
executable
file
that
it
can
build
and
run
and
so
that,
to
that
end,
it
wraps
it
in
the
main
function,
if
there's
not
one
already
and
then
as
an
actual
reference
to
your
crate,
if
it's
not
there
already
and
the
basically
like
the.
In
short,
that's
basically
what
it
does,
there's
kind
of
more
things
that
I
get
into
like.
A
If
you
have,
if
you
have
the
tests
that
depend
on
a
certain
unstable
feature,
you
don't
have
to
write
the
main
function
yourself.
So
if
you
have
this
sick
rad
feature
here
that
will
automatically
get
placed
outside
of
your
the
main
function
that
Russ
stock
puts
in
and
same
with,
when
you
have
to
reference
multiple
crates
at
once.
A
There's
one
last
thing
that
it
does,
because
doc
tests
can
kind
of
hit
a
few
style
lengths
that
are
pretty
common.
It
adds
this
allow
unused
lint
to
any
used
attribute
to
kind
of
ignore
a
handful
of
Lintz
that
are
common
to
hit
and
doc
tests
like
in
the
one
that
I
got.
I
assigned
this
my
struct
variable
and
I
don't
use
it.
So
that's
an
unused
variable
wind
but
say
we
don't
want
that
say
we
want
to
make
sure
see.
A
We
have
denial
warnings
on
our
crate
and
we
want
to
make
sure
our
doc
tests
are
held
to
the
same
standard.
There's
a
way
to
do
that
with
this
mouthful
of
an
attribute
here,
this
doc
test
adder
can
basically
it
takes
the
insides
of
that
and
replaces
that
crate
attribute
to
allow
unused
with
whatever
you
put
there.
So
here,
I've
replaced
it
with
deny
warnings
and
to
kind
of
show
it
off
like
this
is
kind
of
what
comes
out
of
it
and
to
kind
of
prove
that
it
happened.
A
I
had
that
same
code
snippet
and
tried
to
run
cargo
tests
on
it,
and
naturally
it
complains
with
that
unused
variables.
Lint.
So,
like
the
standard
library,
does
this
a
lot
I
think
it
does?
It
does
deny
warnings
and
but
allows
a
handful
of
like
deprecated,
so
that
it
can
document
deprecated
things,
and
so
it
uses
this
to
kind
of
control,
to
make
sure
that
it's
doc
tests
or
halls
are
the
same
standard
as
its
code,
so
to
kind
of
lead
into
the
next
section.
A
It's
worth
noting
that
rustic
liens
on
the
compiler
a
lot
to
run
through
your
crate
and
get
all
of
the
information
out
of
it.
So
it's
these
dot
comments
that
you
may
or
may
not
have
seen.
Those
are
actually
specially
recognized
by
the
compiler
they're,
effectively
aliases
for
these
doc
attributes
here.
A
A
Leaning
on
that,
the
doc
attribute
itself
has
a
few
kind
of
overloaded
things.
I
mentioned
one
earlier
with
that
doc.
Test
attribute
one
but
there's
several
others
that
it
uses
the
just
kind
of
like
lists
these
off
HTML
root.
Url
is
something
you
can
use
to
control,
how
other
crates
link
to
yours
when
they
use
your
crate
as
a
dependency.
So,
like
the
standard
library,
does
this
to
make
links
go
to
night?
A
The
nightly
Doc's
several
crates
use
this
to
link
to
doc
star
s
instead
of
just
noting
if
their
docks
aren't
made
locally
dock
in
line
and
dock
no
in
line
are
ways
to
handle
re-export
statements.
So
if
you've
used
or
seen
a
pub
use
statement
to
sort
of
publicly
relocate
something
from
one
portion
of
your
crate
to
another,
rustic
can
handle
those
based
on
how
the
original
is
visible
to
either
copy
in
the
that
other
things
docks
or
not.
A
A
Dock
hidden
is
kind
of
a
way
to
control
what
things
are
actually
visible
in
your
docks.
So
if
you
have
your
code
base
split
up
into
multiple
crates
and
you
have
something
that's
technically
an
implementation
detail
and
you
don't
actually
want
to
expose
it
as
public
API,
you
can
slap
duck
hidden
on
it,
so
that
it's
still
exported
and
other
crates
can
use
it,
but
it
won't
appear
in
your
documentation.
So
you
have
this
sort
of
unwritten
expectation
that
okay,
this
is
not
meant
to
be
used
in
that
way.
A
So
it's
just
meant
for
people
who
work
with
the
code
directly
I
know,
I,
think
the
standard
library
does
this
on
the
I/o
or
enum.
It
has
this
like
non-exhaustive
variant
of
it,
that
it
slap
stock
hidden
on
to
make
it
appear
that
you
can't
match
on
the
I/o
error.
You
know
I'm
exhaustively
things
like
that,
and
you
can
say
this
is
an
implementation.
Detail
don't
depend
on
this.
A
Dock
include
is
a
relatively
relatively
recent
addition.
It's
still
unstable
to
use
needs
a
future
attribute
and
what
this
does
is
it
makes
it
so
that
say,
if
you
have
like
the
standard
library,
a
whole
lot
of
docks
on
one
thing:
it
kind
of
blows
up
your
source
files,
and
it
has
a
lot
of
this
empty
text
that
has
it's
not
relevant
to
the
compilation
of
your
code,
but
it
prevents
you
from
seeing
a
on
one
page
with
Doc
include.
You
can
say:
I'm,
not
gonna,
write
this
as
doc
comments.
A
I'm
gonna
write
this
in
a
separate
file.
Hey
Russ
talk
copy
paste
that
in
whenever
you
run,
and
you
can
have
your
documentation
in
separate
files
so
that
you
can
track
it
separately
and
they
don't
get
in
the
way
of
the
code
of
your
library
in
doc.
Cfg
is
content
as
the
subject
of
the
next
few
slides.
So
if
you've
rummaged
around
the
standard
library
for
a
while,
you
may
have
noticed
this
os
module
in
it
and
on
the
officially
hosted
docs.
A
So
I
have
this
another
demo
project
up
here
that
uses
these
traits
in
staros
to
get
the
size
of
the
file.
I.
Think
the
actual
metadata
straps
these,
but
for
the
purposes
of
this
demo,
I
just
have
these
platform
specific
things
in
here
and
I
ran
the
docs
on
Linux
and
I
ran
the
docs
on
Windows
and,
as
you
can
see,
it's
different
depending
on
what
system
you
actually
ran
the
rusick
executable
on
so
to
get
around
this.
You
might
first
think
well.
Rostock
doesn't
need
to
actually
fully
compile
the
code.
A
A
There's
a
caveat
about
the
the
codes
featured
here
that
CFG
Rostock
is
supposed
to
be.
There's
an
open
PR
to
make
this
so
that
when
our
stock
is
running,
that's
set
right
now.
The
suggested
way
to
do
this
is
by
using
a
carpet
feature,
so
you
would
type
cargo
feature
docks
or
whatever
and
use
that
as
your
conditional
compilation.
A
But
and
in
any
case
you
tell
Russ
doc,
hey
this
thing
is
available
on
our
utility
compiler.
This
thing
is
available
both
on
UNIX
and
whenever
I'm
building
docks
or
on
Windows
and
whenever
I'm
building
dogs
and
if
you're,
just
building
your
docks,
you
get
both
things.
There
cool
problem
solve
right
kind
of
say:
you
have
dog
tests
on
these
that
use
these
items.
A
Well
now
you
need
to
build
and
execute
those
tests
as
executables,
which
means
they
need
to
link
against
the
platform
libraries
which
may
not
be
available
on
the
platform
where
you're
running
Russ
doc.
So
here
I
made
a
couple
empty
doc
tests
that
just
called
the
thing
and
I
ran
around
the
living
system
and
the
windows
size
function
is
not
available
because
I'm
not
running
on
Windows.
A
So
to
get
around
this,
that's
where
the
doc
CFG
attribute
comes
in.
So
this
was
introduced
to
get
the
stud
OS
module
that
I
showed
earlier
to
make
all
these
things
come
together,
and
so
this
is
the
problem.
It
really
solves.
Is
that,
yes,
you
can
tell
Russ
talk
about
all
of
the
things
all
at
once,
but
then
you
can't
have
dog
tests
on
it,
and
but
this
tells
Russ
doc
hey.
This
thing
is
actually
only
supposed
to
run
on
UNIX
or
on
Windows
or
on
little
endian
systems
or
on
x86
64.
A
Whatever
anything,
you
can
slap
the
CFG
on
and
I
put
so
in
the
in
that
dummy
project.
I,
put
doc,
CFG
attributes
on
and
ran
tests
again,
and
it
only
ran
the
UNIX
size
test,
because
now
it
knows
I'm
not
supposed
to
run
the
Windows
one
I'm
not
running
on
Windows
and
the
other
thing
that
it
does
is.
It
creates
those
little
banners
so
that
units
that
square
brackets
units
square
brackets
windows
and
the
blue.
This
is
supported
on
windows
only
banner
the
dock
CFG
attribute
actually
puts
those
in.
A
So
this
is
a
way
you
can
say
outside
of
the
text
that
you
write,
that
this
is
meant
for
this
specific
platform,
this
specific
configuration-
and
so
that's
like
it's
something,
really
cool
that
it
can
do
and
but,
like
I
said,
like
true
handling,
a
conditional
compilation
is
a
bit
of
as
I've
described
it
a
holy
grail
because
of
how
much
it
leans
on
the
compiler.
But
this
is
a
good
compromise
if
you
can
be
conscious
of
I'm
running
of
when
you're
running
dogs,
so
moving
on,
in
addition
to
attributes
that
it
uses
they're.
A
Also
a
handful
of
CLI
flags
that
you
can
use
so
I've
just
listed.
A
bunch
here
of
note
is
the
the
document
private
items
attribute,
which
is
really
nice.
If
you
want
to
have
a
separate
set
of
docs
for
when
you're
writing
on
the
crate
in
question,
what
that
will
do?
Is
it
usually
when
Russ
doc
runs,
it
actually
will
remove
and
not
show
items
that
are
internal
to
your
great.
A
You
can
do
that
so
two
hand
flags
to
Rostock
via
cargo.
There's
this
cargo
rest
command
and
you
can.
You
can
use
that
and
it
will
run
docks
on.
Just
your
crate
and
hand,
these
extra
attributes
that
you
give
it
to
Rostock
whenever
it
calls
it
so
I
added
this
extra
file.
Here,
that's
just
a
tiny
HTML
snippet
and
it
adds
a
little
positive
affirmation
to
your
docks.
A
As
far
as
practical
applications,
the
the
curve,
two
five
five
one
nine
Dalek
library
and
its
internals
docks.
It
actually
fully
writes
out,
like
the
mathematical
formulas
and
symbols
for
like
the
like
theory
behind
what
it's
doing,
and
it
uses
this
Cossack
library
to
lay
that
out
and
it
uses
HTML
and
header
to
pull
that
library
in
so
that
all
its
Doc's
can
use
it
and
there's
also
an
impractical
application.
You
can
do
in
case.
You
want
to
plus
your
Doc's
with
ponies.
A
A
So
this
is
kind
of
what
popularized
this
I
guess:
Henry
valence
and
Isis
Lovecraft's
kind
of
put
this
together
and
you're
gonna
talk
to
me
first
when
they
were
putting
it
together,
and
it's
a
shame
that
they're
in
the
next
room
talking
right
now
and
basically
said
well.
This
is
something
that
we
can
use
to
render
contact
and
then
they
looked
at
it
and
said
well,
Doc's
RS!
You
can
hand
that
arbitrary
arguments
in
the
configuration
there
and
the
crate
docks
of
ponies.
A
You
can
see
and
well
how
about,
if
we
just
add
in
the
thing
that
plasters
ponies
all
over
your
web
page
and
do
it
to
your
Doc's
and
they
give
you
like
the
ponies
crate.
If
you
go
to
that
URL,
they
give
you
instructions
as
to
how
to
do
it
and
so,
like
it
kind
of
started,
a
conversation
as
to
what
counts
as
what
they
call
XSS
cross-site
ships,
cross-site
scripting,
but
in
my
mind,
is
just
kind
of
a
novel
use
of
features
that
are
already
there.
A
So
I
think
it's
kind
of
funny,
so
I
do
have
a
little
bit
of
time.
So,
let's
take
a
second
to
kind
of
look
at
what
goes
on
under
the
hood,
so
Russ
doc
has
been
a
rap
has
been
around
for
a
while
I
kind
of
mentioned
that
in
a
minute,
but
it
lives,
it's
code,
lives
in
the
compilers
repo
right
alongside
the
compiler
and
the
standard
library.
A
So
if
you
look
in
the
the
rust
repos
source
directory
in
the
middle
of
the
massive
list
of
subfolders,
there
there's
a
little
one
called
Lib
Russ
doc
and
that's
where
all
of
Russ
talks
code
lives
and
so
like
all
of
the
all
of
the
stuff
that
it
adds
on
top
of
the
compiler
lives
there
I
as
a
side
note,
Russ
talk
is
kind
of
old
like
this.
Is
the
PR
I,
dug
it
out
that
first
added
the
very
small
bare-bones
things
that
scraped
out
doc
attributes
this
was
before.
A
I
was
talking
with
someone
else
this
morning.
Apparently
this
was
before
doc.
Comments
were
a
thing,
so
I
just
have
like
the
timeline
there,
July
2009
graden
started
like
writing
on
rust
as
a
private
project.
Shortly
after
it
was
made
public
and
then
in
April
2011,
it
switched
from
being
written
in
oh
camel
to
written
in
rust
itself,
so
I
started
self
hosting.
Just
a
few
months
later,
Russ
stock
was
added,
so
Russ
talk
is
almost
as
old
as
the
compiler.
A
This
means
a
lot
of
hands
have
been
placed
on
it
and
it's
a
little
it's
a
little
curse
in
a
sense.
I
have
this
joke
and
a
handful
of
friends
that
rustic
kind
of
occasionally
kind
of
gets
its
information
by
not
kosher
methods.
So
first
we
asked
nicely
there's
the
actual
compiler
things
that
the
compiler
does
for
what
it
does,
and
sometimes
we
have
to
go
to
around
that.
Somehow
so
I
mentioned
the
talk--I
attribute
earlier.
That
doc
attribute
is
actually
fully
white
listed
about
the
compiler.
A
The
compiler
just
ignores
the
doc
attribute
it
passes
it
through,
but
it
doesn't
do
anything
with
it.
So
Russ
doc,
I
know
I've
used
that
personally,
whenever
I've
added
an
extension
attribute
or
us
dog
to
just
hack
on
it
and
deal
with
it
later,
occasionally
we
have
to
break
the
compiler
to
we
want
so
I
have
notes
here
the
there's
a
feature
called
introduc
links
where
you
can
write
your
link
target
to
point
at
a
type
instead
of
the
actual
HTML
page.
A
To
do
that,
we
had
to
break
the
compiled
hello,
because
name
resolution
happens
before
the
part
that
Rostock
usually
runs
at.
So
we
had
to
reorder
TechEd
part
of
the
compiler
to
be
able
to
help
lotta
that
information
and
if
things
get
drastic
enough,
we
threatened
to
break
the
compilers
friends
so
a
couple
years
ago,
maybe
a
year
and
a
half
ago,
the
way
that
the
compiler
was
built
changed
and
Russ
talk
really
benefited
from
that.
A
It's
great
and
then
also
there
is
this
way
you
can
there's
this
function
and
they're
called
pretty
printing
that
has
a
handful
of
like
transformations
on
the
code
and
one
of
the
things
that
it
does
is
there's
this
version
called
everybody
loops
that
replaces.
Yes,
there
are
places
all
function
bodies
with
a
empty
loop
statement,
because
empty
loop
statements
type
check
to
everything,
because
nothing's
coming
out
of
that.
A
So
this
was
done
actually,
when
the
stud
OS
Doc's
were
put
in,
because
if
you're
not
referencing,
anything
inside
your
functions,
now
you
no
longer
have
to
worry
about.
What's
in
there
now,
you
no
longer
have
to
worry
about
accidentally
referencing
platform
stuff.
So
because
of
the
way
I've
laid
this
out,
the
inside
joke
is
that
Russ
talk
is
kind
of
like
the
Mafia,
but
it
provides
a
central
community
service.
So
no
one's
really
tried
to
stop
it.
A
A
Have
a
couple
slides
here
that
I'm
gonna
actually
gloss
over
if
you
read
the
full
slides
I,
have
them
online
that,
like
here's,
the
full
compiler
process
of
what
it
does
like
I
mentioned,
it's
the
jargon,
filled
versions,
I'm
kind
of
glossing,
cuz
we're
getting
close
to
time,
but
here's
a
few
highlights.
So
if
you've
looked
around
these,
this
is
kind
of
like
I
circling
back
to
fun,
things
that
are
in
the
display
of
documentation.
If
you've
noticed
for
a
couple
versions.
Now,
there's
been
these
auto
trade
implementations.
A
So
this
is
novel
because
that
sin
dimple
doesn't
exist
anywhere
right
because
rest
docks
crates,
scrapes
the
text
of
your
crate
effectively
it
used
to
not
even
say
that
vac
implemented
sends
or
sync
at
all,
you
just
kind
of
had
to
assume
that.
Well,
if
the
items
and
the
vac
are
sinkers
and
then
that
transfers
to
the
vac
now
that's
made
obvious,
but
to
do
that,
we
had
to
break
the
compiler
so
that,
because
we
had
to
basically
make
up
these
dimples
on
the
spot.
A
Another
fun
highlight
is
that
Russ,
lock,
outputs
HTML,
but
it's
templating
engine
is
a
gigantic
right
macro
call.
This
is
this
is
this
is
literally
like
in
the
in
the
Russ
talk
source.
There
is
this
file
that
it's
just
like
a
massive
skeleton
of
the
HTML
page
and
everything
gets
written
in
there,
and
so
everything
that
needs
to
be
printed
implements
display
and
it's
just
slots
in
there
internals
wise
Russell
Arc
has
its
own
test.
A
But
it's
you
know
it's
just
kind
of
fun.
If
you're
interested
in
kind
of
the
gory
internals
of
how
a
stock
documentation
goes
from
crate
to
Docs,
it's
pretty
fun
but
as
they
close,
you
may
or
may
not
want
to
actually
follow
me
on
Twitter.
But
if
you'd
like
to
verify
that
claim,
that's
my
handle.
Otherwise,
that's
all
I've
got.