Rustdoc actually renders the source code itself, and puts little [src]
links on (most) things, e.g. the [src] link on the top right of the
arena crate docs links to
http://static.rust-lang.org/doc/master/src/arena/home/rustbuild/src/rust-buildbot/slave/doc/build/src/libarena/lib.rs.html#11-597
However, this isn't as good as it could be, e.g. the link is easy to
miss, and:
- https://github.com/mozilla/rust/issues/12926
- https://github.com/mozilla/rust/issues/12932
Huon
On 19/03/14 11:20, benjamin adamson wrote:
I recently had to learn enough Ruby at work to implement some new
behavior to a relatively old program. I ran across one website where
the documentation of the API I was learning was embedded into the HTML
directly. Having immediate access to the source code allowed to
understand what the API was doing more-so than the actual
documentation.This was immensely helpful, and I'm wondering (hoping)
that Rust could steal the motivation for this idea. Here is an
example, the source code is embedded onto the page:
http://apidock.com/ruby/URI/HTTP/request_uri
As a developer having as much information as possible is what I always
want. My idea is to provide a link on the generated documentation page
that links to the source code on github. I think that's a little more
sane then having the source code embedded into the generated HTML.
As an example, currently I'm looking at the documentation for an
arena, http://static.rust-lang.org/doc/master/arena/index.html and it
would be *convenient* for the documentation to link to
https://github.com/mozilla/rust/blob/master/src/libarena/lib.rs
There's a ton of useful documentation about the Arena in the source
code the user can read too,
https://github.com/mozilla/rust/blob/master/src/libarena/lib.rs#L66
for example. Any shortcomings of the documentation can be some-what
circumvented if the user wants to just look at the source code. I want
to make one thing clear, I understand that users can go on github and
find the source-code, this feature would just automate that
(potentially distracting/long/difficult task, especially for newcomers
to Rust) step reducing barrier to entry.
Another benefit is that this would get more rust users looking at the
source code, possibly leading to more PR's improving documentation or
implementation (educated guess). Furthermore users can understand
performance implications of using any public library, conveniently.
This may be really useful for users of under-documented
modules/libraries. This might be an immensely useful addition to
Rust's documentation.
_______________________________________________
Rust-dev mailing list
[email protected]
https://mail.mozilla.org/listinfo/rust-dev
_______________________________________________
Rust-dev mailing list
[email protected]
https://mail.mozilla.org/listinfo/rust-dev
