Missing documentation on a lot of modules
applejag opened this issue · 20 comments
There's a lot of modules in https://github.com/risor-io/risor/tree/main/modules
Would be nice with docs on all of them, instead of having to skim through the source code.
The current status, as far as I can see:
- aws
- base64
- bytes
- risor-io/risor-site#1
- filepath
- fmt
- http
- image
- json
- math
- os
- pgx
- rand
- regexp
- sql
- strconv
- strings
- template
- time
- uuid
- vault
Indeed! Thanks for putting together the list of gaps.
@myzie I can't find where the docs are coming from. Are they git-based?
I could try help with some of those docs
The docs are in Git but are not open source at the moment, however I should probably just go ahead and switch that.
The reason I didn't already do that is that the code editor and integration with the AWS Lambda backend for the Risor eval API is in there too. And I didn't review all that yet to see if it was going to be safe for open source contributions.
Potentially I could move the markdown docs to this repo and then use a GitHub action to push them to a separate private site repo before publishing them or something that. I'll look into it.
Would be great to have some docs generation, to keep it up to date.
Don't know what would be the best solution, but what if you picked a documentation syntax for inside Risor, and then use that?
The "example test" feature of Go is such a powerful one, as then your docs become testable.
Maybe worth taking inspiration from that?
For example, what if there was a risor file that just includes the definitions of the builtins, and makes use of example tests?
// Returns `true` if all objects in the given container are "truthy".
//
// @param {list} container
// @return {bool}
func all(container);
example all { all([true, 1, "ok"]) } = true
example all { all([true, 0, "ok"]) } = false
// Printf wraps `fmt.Printf` in order to print the formatted string and arguments to stdout.
// In the Risor REPL you will currently not see the `printf` output unless the string ends
// in a newline character.
//
// @param {string} format
// @param {any} args
func printf(format, ...args);
// ^Risor doesn't have syntax for variadic functions in its syntax. Needs to be added.
example printf {
printf("name: %s age: %d\n", "joe", 32)
// @stdout
// name: joe age: 32
//^not sure about how to handle output though...
}
// Returns a new set containing the items from the given container object.
//
// @param {any} container
// @return {set}
func set(container);
example set { set("aabbcc") } = {"a", "b", "c"}
example set { set([4,4,5]) } = {4, 5}
example set { set({one:1, two:2}) } = {"one", "two"}The @param {any[]} container syntax is inspired by JSDoc (https://jsdoc.app/tags-param). Could be nice to have dedicated syntax for it, but as Risor doesn't have syntax for types then I think it'll have to be in the comments somehow.
The example all statement could be a custom docs syntax just for defining examples. My example is just inspired by the Zig test statements (https://ziglang.org/documentation/master/#Zig-Test). Just toying with syntax, of course nothing final.
Benefit would be that then people could write docs for their own modules too.
I really like the overall direction of all these suggestions:
- Some level of generating docs from the code
- Runnable examples in the code, which end up as runnable examples on the docs webpages too
- I tend to agree that having the ability to mix examples, tests, and code in the same file feels aligned with a lightweight scripting setup like Risor. Requiring separate test files feels relatively heavyweight which isn't fitting here.
At first glance, I like Zig's approach that you linked to well enough. Having first-class syntax for defining examples and/or tests seems appropriate.
One aspect of what Rust has that has appeal on the surface is Markdown conventions that are functional via section headers like #Examples and so on. https://doc.rust-lang.org/rust-by-example/testing/doc_testing.html
Although I think Rust's approach leading to /// at the start of every line is tiresome to look at in the source code.
Continuing to brainstorm some options would be great. I'll keep thinking on it.
Yea the /// isn't great.
Back to Zig, they use //!, which also looks weird (https://ziglang.org/documentation/0.11.0/#Top-Level-Doc-Comments)
Relying on basic comments should suffice though. While coding in Go, I've never felt the lack of distinction between regular comment and doc comment was bad.
You start developing new styles, that works just as fine. Such as:
// Some comment that is related, but omit it from docs.
// Done by just having an empty line in between.
// MyFunc blah blah doc comments
func MyFunc() {
// Sometimes just placing the non-doc comments here works too.
}Sometimes there's definitely need to write comments for a function that you don't want included in the docs, but introducing separate syntax for it always felt excessive to me.
As for doc comments being regular markdown is smart I think.
Go wanted to stay out of this, with the argument that it's bad to mix languages in the same file, and to keep it simple.
But in practice, they've slowly been adding markup features to their doc comments (like lists and links), so now it's just another markup language to learn.
Most devs are so used to Markdown nowadays anyways (or at least the basics, like inline `code blocks`, **bold**, _italics_, [links](...)), that going with anything else would just be pain.
@applejag - fyi the Risor.io site is now open source:
https://github.com/risor-io/risor-site
fyi the Risor.io site is now open source:
https://github.com/risor-io/risor-site
Sweet! Nice job
Maybe move this issue to that repo?
Could extract the "doc comments in Risor" part into its own issue in this repo
Something like this? https://github.com/princjef/gomarkdoc
Something like this? https://github.com/princjef/gomarkdoc
Yeah! But where the Risor comments are using Markdown too.
I'm thinking about doc links, where you can easily link to docs of modules and their symbols (like Go's // Implements [fmt.Stringer] syntax). Maybe it's better to just wait with adding such syntax until later, but a spontaneous idea would be to use wiki-style links for that.
Some Markdown flavours support wiki-style links [[my-link]] (especially common in note taking, such as Obsidian). This could be used to link the same way Go has their doc links.
So that:
[[json#marshal]]links to https://risor.io/docs/modules/json#marshal[[foobar#baz]], where foobar is an imported foobar.risor file, links to./path/to/foobar.md#baz
Another thing we could do is to add some synopsis field/method to the builtins, that could be useful in the relp to get some info on how to use a command/function and could also be used to generate markdown docs and man pages, Kind of like what cobra has...
I’m working on something like that for builtins and modules. Prototyping using go embed to include md files. Will share a branch in the next couple days hopefully.
I’m working on something like that for builtins and modules. Prototyping using go embed to include md files. Will share a branch in the next couple days hopefully.
I see that you've added go:embed here and there, such as in the fmt module. Why is that? It seems unused?
Also, since you've added a bunch of the docs, then I guess I can just close my PR risor-io/risor-site#1 ?
@applejag - I wasn't receiving notifications for any of your comments and PRs in the risor-site repo, so I totally missed all your activity there.
You brought up a bunch of good questions so I will be reviewing all that.
@applejag - If you want, join gophers.slack.com and the #risor channel in there. That's just another good way to coordinate.
@applejag - I wasn't receiving notifications for any of your comments and PRs in the risor-site repo, so I totally missed all your activity there.
Don't worry about it. The docs you wrote are also good, so I'm honestly fine with just closing mine
@myzie I've opened #165 to add the missing docs for the modules I've added recently but I think in the future we need a solution to generate these, I think using comments with a special tag would work well, we can either come up with our own conventions like // risor:docs:signature; // risor:docs:example; // risor:docs:summary, etc... or use some existing solution but that might not give us the exact format that we want for the website....
That sounds good @luisdavim. As long as we don't have to parse markdown!