Are you writing docstrings right?

Hello all!

Today’s post is about some underused inbuilt features specific to Cargo.

Cargo-Logo-Small

People who have been using Rustlang would mostly be using Cargo as their default package manager and turns out it offers a wide variety of features. Its like Cargo picked up all things good from all other package managers and added Chemical X to make itself so powerful.

We are going to see a feature that is mostly missed while writing code. Do you know you could write docs inside the code and compile it to generate an HTML document using no other packages? Example below.

Screenshot from 2019-12-11 14-33-19

You could just do

cargo doc

and cargo will create an HTML doc for you which you can open up with

cargo doc –open

And it would look like *drumroll*

Screenshot from 2019-12-11 13-59-06

If you click on get_coffee_type, you would see

Screenshot from 2019-12-11 14-00-35

Awesome. Right?

While this is awesome, this is not what what I brought you so far for.

The Super Awesome part

Cargo runs the code in docstrings as tests! I know. Craaazy, right?

So, if you go ahead and do

cargo test

You will see

Compiling cargo_doc v0.1.0 (/home/tuxish/Blogs/blog-code-snippets/cargo-doc)
Finished dev [unoptimized + debuginfo] target(s) in 0.31s
Running target/debug/deps/cargo_doc_test-7d80c71a795266a7

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Running target/debug/deps/cargo_doc-f935d2eea739d26d

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Doc-tests cargo_doc_test

running 1 test
test src/lib.rs – get_coffee_type (line 6) … ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

3j3ccr

Yep. Test without even writing a test. Haha.

How does this help?

Let’s say there is some disagreement about the way Latte should be made, say somebody would call a Latte a Latte if only it has at least 5 pours of steamed milk. Now, we change the code right away but forget updating the docs, well, tests would fail for you then.

Compiling cargo_doc v0.1.0 (/home/tuxish/Blogs/blog-code-snippets/cargo-doc)
Finished dev [unoptimized + debuginfo] target(s) in 0.25s
Running target/debug/deps/cargo_doc_test-7d80c71a795266a7

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Running target/debug/deps/cargo_doc-f935d2eea739d26d

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Doc-tests cargo_doc_test

running 1 test
test src/lib.rs – get_coffee_type (line 6) … FAILED

failures:

—- src/lib.rs – get_coffee_type (line 6) stdout —-
Test executable failed (exit code 101).

stderr:
thread ‘main’ panicked at ‘assertion failed: `(left == right)`
left: `”Latte”`,
right: `”Cappuccino”`’, src/lib.rs:8:1
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace.

failures:
src/lib.rs – get_coffee_type (line 6)

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out

i871j

This is such an underused fascinating feature. Try and use this to keep your code and docs in sync if you haven’t been doing it already.

Python also provides similar doctest in case you are interested.

Do you know of any other such cool features of Cargo that are not used a lot? Comment below.

You can find the code sample used in this post here.

Thanks for reading. Have a good day! 🙂

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s