A few weeks ago, I mentioned Rust Doc Days. This was an event where the Rust community made a conscious effort to improve Rust’s documentation. Throughout this blog post, “we” refers to the quasi-official Rust docs team.
How did it go? The first Rust Doc Days was, we felt, a successful event. We deliberately kept the event low key to try to work the kinks out. Over the two days, a few pull requests with new documentation were made.
Documentation is important. It’s also easy to do. Rust ships with tools to help developers create documentation for their libraries.
Code Comments The main way that many developers write documentation is through source code comments. A single-line comment in Rust is started with //. Many programming languages should already use this construct, so it’s probably not surprising to you. Equally unsurprising, multi-line comments start with /* and end with */. Many Rustaceans (that’s what Rust developers call themselves) prefer single-line comments.
[caption id=“attachment_1034” align=“alignright” width=“300”] Liberate your output pipes from the tyranny of programmatic control![/caption] Let’s say you have to work with OS processes - you’re building tools for automation and you need to capture the output of a command with your Rust program. You might need to process the command’s output and do something with it, but you also need to send that output back to the usual location (usually stderr or stdout).
We previously talked about The Basics of Rust structs. That was some pretty cool stuff - we learned how to structure data and how to attach functionality to that data by using impl. A struct defines what data we have, but what if we want to define how that data should function? [caption id=“attachment_1031” align=“alignright” width=“300”] Using the traits Rusting and Broken at the same time.[/caption]
Enter Rust’s Traits A trait lets us define how data will behave.
[caption id=“attachment_1026” align=“alignright” width=“300”] Pretty structs, as far as the eye can see…[/caption] structs are one of the basic building blocks in Rust. A struct lets us create more complex data types of our own. Instead of having to jump through naming hoops to make our own data structures, we can create whatever we want.
Our First Rust struct Let’s look at creating a simple struct for a to do application.
I’ve been doing some programming in Rust recently. First was a flake generator and then the second is a rudimentary implementation of the ls command (dir to Windows people) - I submitted a pull request to uutils/coreutils: a replacement for the UNIX coreutils suite of software. Error handling plays a big role in both of these chunks of code - making sure users don’t get a nasty surprise requires making sure you let them know when things go wrong.
UPDATE 2020-10-25 This post is over 4 years old. You don’t need it. Go to rustup.rs. Do whatever that tells you. You don’t need the rest of this.
Installing Rust can be as easy as pulling down an installer and double clicking. For developers working with more complex tools or who need to build unsafe C/C++ libraries from source, there’s a little bit of extra work that needs to be done, but it’s nothing that a savvy person can’t handle.