Using Rust at docgrandma

Rust Basel 2020-12-07

docgrandma

in a nutshell

Mission

To improve documentation of software projects effortlessly

The problem

All code has documentation debt. Dev teams have three options:

  1. Dedicated cleanup work
  2. Bureaucracy for new code
  3. Live with the debt

The solution

Regularly ask developers specific, brief doc questions that are fun to answer.

Sustainably reduce documentation debt one question at a time.

inspiration

  • My struggle to keep documentation in sync or write good comments in general
  • The talk from Beth Aitman at Rust Zurich ~2 years ago

Rust values good docs

  • rustdoc
  • doctests

Source: https://www.quora.com/Why-are-coders-so-bad-at-writing-documentation-that-is-easy-to-understand-for-the-average-human-programmer

But it's the engineers who know the code...

MVP launching soon

Key Success Factors

  • easily integrate into existing workflows and tools
  • additive (so it can be "tried out" without being part of a CI strategy beforehand)
  • When is the right moment to ask the developer?

Team

MVP tech stack

? 👥

Product validation tech stack

  • should have started with this

Product market fit?

  • Code comments are a polarizing issue
  • The pragmatic programmer put comments slightly out of favor
  • New language features like doctests are becoming mainstream -> comments are cool again? 🕶️

parsing code with pest

WHITESPACE = _{ " " | "\t" | "\r" | "\n" }

// top level rule
file = {
    SOI
    ~ (import_stmt)*
    ~ (doc_node)*
    ~ EOI
}

doc_node = {
    (import_stmt)*
    ~ block_comment?
    ~ (import_stmt)*
    ~ block
}

block_comment = { "/*" ~ (!"*/" ~ ANY)* ~ "*/" }

block = { (function | typedef) ~ block_body }

block_body = { "{" ~ "}" | "{" ~ body_inner* ~ "}" }

Rust for MVPs you can keep

use crate::scanner::DocNode;
use std::fs;
use regex::Regex;
use regex::escape;
use regex::Split;
use std::env::current_dir;

pub fn commit(mut new_comment: String, doc_node: DocNode, pwd: &str) {
    let mut complete_file = fs::read_to_string(&doc_node.file).unwrap();
    // construct the comment from new_comment
    new_comment = "/*\n * ".to_owned() + &new_comment + " \n */\n";
    let sandwich: Vec<&str> = complete_file.split(&doc_node.code).collect();
    assert!(sandwich.len() == 2);
    let complete_file = sandwich[0].to_owned() + &new_comment + &doc_node.code + sandwich[1];
    fs::write(&doc_node.file, complete_file).unwrap();

    use std::process::Command;
    let cmd = format!(
            "cd {} && git add {} && git -c core.hooksPath=/dev/null commit -m 'a little improvement by docgrandma'",
            pwd,
            &doc_node.file.to_str().expect("not found")
    );
    Command::new("bash")
        .arg("-c")
        .arg(cmd)
        .output()
        .expect("some error with the commit");
}

Experiences

  • Rust can work for startups, but be careful
    • Libraries like slack client take more time to get productive -> Javascript is better there
    • Steep learning curve
  • Pest is awesome, even compared with parser generators from other platforms
  • Rust is good for writing your libraries
    • single binary
    • good FFI
  • Rust has trouble keeping up with reference implementations in other language.
    • For most things web today, the reference implementation is in JS
    • Example: Slack Client

Misc.

  • Tipps for doing stackoverflow questions?
  • I'm thinking about a rust youtube channel. What would be interesting?
  • Mark Monday, Feb 8 in your calendar right now for the next Rust Basel

Next

  • Closed user testing group -> PM me if interested!

using rust at docgrandma

By Roland Brand

Made with Slides.com

using rust at docgrandma

  • 66

More from Roland Brand