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 Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
