Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
int
Rust
提交
2fa53403
R
Rust
项目概览
int
/
Rust
大约 1 年 前同步成功
通知
1
Star
0
Fork
0
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
DevOps
流水线
流水线任务
计划
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
R
Rust
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
DevOps
DevOps
流水线
流水线任务
计划
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
流水线任务
提交
Issue看板
体验新版 GitCode,发现更多精彩内容 >>
提交
2fa53403
编写于
8月 12, 2017
作者:
B
bors
浏览文件
操作
浏览文件
下载
差异文件
Auto merge of #43792 - steveklabnik:rustdoc-directives, r=frewsxcv
Document the doc attribute cc #42322
上级
b8266a90
1e4aaea4
变更
3
隐藏空白更改
内联
并排
Showing
3 changed file
with
179 addition
and
4 deletion
+179
-4
src/doc/rustdoc/src/SUMMARY.md
src/doc/rustdoc/src/SUMMARY.md
+1
-1
src/doc/rustdoc/src/in-source-directives.md
src/doc/rustdoc/src/in-source-directives.md
+0
-3
src/doc/rustdoc/src/the-doc-attribute.md
src/doc/rustdoc/src/the-doc-attribute.md
+178
-0
未找到文件。
src/doc/rustdoc/src/SUMMARY.md
浏览文件 @
2fa53403
...
...
@@ -2,7 +2,7 @@
-
[
What is rustdoc?
](
what-is-rustdoc.md
)
-
[
Command-line arguments
](
command-line-arguments.md
)
-
[
In-source directives
](
in-source-directives
.md
)
-
[
The `#[doc]` attribute
](
the-doc-attribute
.md
)
-
[
Documentation tests
](
documentation-tests.md
)
-
[
Plugins
](
plugins.md
)
-
[
Passes
](
passes.md
)
\ No newline at end of file
src/doc/rustdoc/src/in-source-directives.md
已删除
100644 → 0
浏览文件 @
b8266a90
# In-source directives
Coming soon!
\ No newline at end of file
src/doc/rustdoc/src/the-doc-attribute.md
0 → 100644
浏览文件 @
2fa53403
# The `#[doc]` attribute
The
`#[doc]`
attribute lets you control various aspects of how
`rustdoc`
does
its job.
The most basic function of
`#[doc]`
is to handle the actual documentation
text. That is,
`///`
is syntax sugar for
`#[doc]`
. This means that these two
are the same:
```
rust,ignore
/// This is a doc comment.
#[doc
=
" This is a doc comment."
]
```
(Note the leading space in the attribute version.)
In most cases,
`///`
is easier to use than
`#[doc]`
. One case where the latter is easier is
when generating documentation in macros; the
`collapse-docs`
pass will combine multiple
`#[doc]`
attributes into a single doc comment, letting you generate code like this:
```
rust,ignore
#[doc
=
"This is"
]
#[doc
=
" a "
]
#[doc
=
"doc comment"
]
```
Which can feel more flexible. Note that this would generate this:
```
rust,ignore
#[doc
=
"This is
\n
a
\n
doc comment"
]
```
but given that docs are rendered via Markdown, it will remove these newlines.
The
`doc`
attribute has more options though! These don't involve the text of
the output, but instead, various aspects of the presentation of the output.
We've split them into two kinds below: attributes that are useful at the
crate level, and ones that are useful at the item level.
## At the crate level
These options control how the docs look at a macro level.
### `html_favicon_url`
This form of the
`doc`
attribute lets you control the favicon of your docs.
```
rust,ignore
#![doc(html_favicon_url
=
"https://example.com/favicon.ico"
)]
```
This will put
`<link rel="shortcut icon" href="{}">`
into your docs, where
the string for the attribute goes into the
`{}`
.
If you don't use this attribute, there will be no favicon.
### `html_logo_url`
This form of the
`doc`
attribute lets you control the logo in the upper
left hand side of the docs.
```
rust,ignore
#![doc(html_logo_url
=
"https://example.com/logo.jpg"
)]
```
This will put
`<a href='index.html'><img src='{}' alt='logo' width='100'></a>`
into
your docs, where the string for the attribute goes into the
`{}`
.
If you don't use this attribute, there will be no logo.
### `html_playground_url`
This form of the
`doc`
attribute lets you control where the "run" buttons
on your documentation examples make requests to.
```
rust,ignore
#![doc(html_playground_url
=
"https://playground.example.com/"
)]
```
Now, when you press "run", the button will make a request to this domain.
If you don't use this attribute, there will be no run buttons.
### `issue_tracker_base_url`
This form of the
`doc`
attribute is mostly only useful for the standard library;
When a feature is unstable, an issue number for tracking the feature must be
given.
`rustdoc`
uses this number, plus the base URL given here, to link to
the tracking issue.
```
rust,ignore
#![doc(issue_tracker_base_url
=
"https://github.com/rust-lang/rust/issues/"
)]
```
### `html_no_source`
By default,
`rustdoc`
will include the source code of your program, with links
to it in the docs. But if you include this:
```
rust,ignore
#![doc(html_no_source)]
```
it will not.
## At the item level
These forms of the
`#[doc]`
attribute are used on individual items, to control how
they are documented.
## `#[doc(no_inline)]`/`#[doc(inline)]`
These attributes are used on
`use`
statements, and control where the documentation shows
up. For example, consider this Rust code:
```
rust,ignore
pub
use
bar
::
Bar
;
/// bar docs
pub
mod
bar
{
/// the docs for Bar
pub
struct
Bar
;
}
```
The documentation will generate a "Reexports" section, and say
`pub use bar::Bar;`
, where
`Bar`
is a link to its page.
If we change the
`use`
line like this:
```
rust,ignore
#[doc(inline)]
pub
use
bar
::
Bar
;
```
Instead,
`Bar`
will appear in a
`Structs`
section, just like
`Bar`
was defined at the
top level, rather than
`pub use`
'd.
Let's change our original example, by making
`bar`
private:
```
rust,ignore
pub
use
bar
::
Bar
;
/// bar docs
mod
bar
{
/// the docs for Bar
pub
struct
Bar
;
}
```
Here, because
`bar`
is not public,
`Bar`
wouldn't have its own page, so there's nowhere
to link to.
`rustdoc`
will inline these definitions, and so we end up in the same case
as the
`#[doc(inline)]`
above;
`Bar`
is in a
`Structs`
section, as if it were defined at
the top level. If we add the
`no_inline`
form of the attribute:
```
rust,ignore
#[doc(no_inline)]
pub
use
bar
::
Bar
;
/// bar docs
mod
bar
{
/// the docs for Bar
pub
struct
Bar
;
}
```
Now we'll have a
`Reexports`
line, and
`Bar`
will not link to anywhere.
## `#[doc(hidden)]`
Any item annotated with
`#[doc(hidden)]`
will not appear in the documentation, unless
the
`strip-hidden`
pass is removed.
## `#[doc(primitive)]`
Since primitive types are defined in the compiler, there's no place to attach documentation
attributes. This attribute is used by the standard library to provide a way to generate
documentation for primitive types.
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录