google / rune

Rune is a programming language developed to test ideas for improving security and efficiency.
Apache License 2.0
1.91k stars 46 forks source link

Enhance README organization, add more background info to code #33

Closed GavinRay97 closed 1 year ago

GavinRay97 commented 1 year ago

Heya,

When I first read the Rune readme, there were a couple of things I thought could be improved:

Also, many people will want to jump directly to specific things ("how do I build this?", "show me a code example?") without reading the rest of it, so I tried to add enough context to each section that it would make sense if you went straight there and skipped the rest.

Lastly, I added some organizational structure and a TOC so folks can navigate the page easier.

Hope this is helpful, I'd like to highlight Rune in the best way possible for potential users as I think it has some neat ideas 🙂


Ahh, one last thing -- I chose the languages for the syntax highlighting for each code block based on which one looked the best/could highlight the majority of the tokens:

Go:

// Check the MAC (message authentication code) for a message.  A MAC is derived
func checkMac(macSecret: secret(string), message: string, mac: string) -> bool {
    computedMac = computeMac(macSecret, message)
    return mac == computedMac
}

Rust (TypeScript comes close too, but not quite as good):

class Human(self: Human, name: string, mother: Human? = null(self), father: Human? = null(self)) {
  self.name = name
  if !isnull(mother) {
    mother.appendMotheredHuman(self)
  }
}
google-cla[bot] commented 1 year ago

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

GavinRay97 commented 1 year ago

Sorry about the random formatting changes that removed only spaces in the diff. VS Code auto-format did that -- I didn't catch it in the PR. I can resubmit if it's an issue.

GavinRay97 commented 1 year ago

I just learned about the dataview tool and figured out what it does, it'd be neat to mention that as well in the README!

image

waywardgeek commented 1 year ago

Thanks for all the work on documentation!