Skip to content

Commit

Permalink
Update intra_rustdoc_links
Browse files Browse the repository at this point in the history
- Mention this is valid Markdown
- Add more alternatives
  • Loading branch information
killercup committed Mar 7, 2017
1 parent 0483d34 commit cacaa79
Showing 1 changed file with 37 additions and 2 deletions.
39 changes: 37 additions & 2 deletions text/0000-intra-rustdoc-links.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,16 @@ it should also be possible to write a Rust path
and somewhere else in the document: `[iter]: std::iter::Iterator`
3. `<std::iter::Iterator>`

All additions are already valid Markdown,
as defined by the orginal [Markdown syntax definition][md]
as well as the [CommonMark] project.
Especially, Rust paths are valid CommonMark [link destinations],
even with the suffixes described [below][path-ambiguities].

[md]: https://daringfireball.net/projects/markdown/syntax
[CommonMark]: http://commonmark.org
[link destinations]: http://spec.commonmark.org/0.27/#link-destination

## How it will be rendered

The following:
Expand Down Expand Up @@ -146,6 +156,7 @@ mod amet {
```

## Path ambiguities
[path-ambiguities]: #path-ambiguities

Rust allows items to have the same name. A short evaluation revealed that

Expand Down Expand Up @@ -271,9 +282,29 @@ Maybe present an example use case of a module whose documentation links to sever
# Alternatives
[alternatives]: #alternatives

## Syntax alternatives
- Use reference-style links and automatically generate the references.
For example, the Markdown snippet

```md
This is of type [`String`].
```

expects a link reference definition like

Introduce special syntax for this:
```md
[`String`]: https://doc.rust-lang.org/nightly/std/string/struct.String.html
```

to follow (or precede) it.
This link reference definition can be automatially generated by Rustdoc
with the (relative) URL to the page of the item.
This was suggested in [the CommonMark forum]
as well as
by [GuillaumeGomez](https://github.com/GuillaumeGomez).

We consider this equivalent to the `<String>` syntax this RFC proposes.

[cm-forum]: https://talk.commonmark.org/t/what-should-the-rust-community-do-for-linkage/2141

- [javadoc] and [jsdoc]
use `{@link java.awt.Panel}`
Expand All @@ -282,6 +313,10 @@ Introduce special syntax for this:
[javadoc]: http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html
[jsdoc]: http://usejsdoc.org/tags-inline-link.html

- [@kennytm](https://github.com/kennytm)
listed other syntax alternatives
[here](https://github.com/rust-lang/rfcs/pull/1946#issuecomment-284718018).


# Unresolved questions
[unresolved]: #unresolved-questions
Expand Down

0 comments on commit cacaa79

Please sign in to comment.