Discussion: Leverage godoc and examples?

[EliRibble]

I've been starting to use this library on a project. In doing so I've felt frustrated by a lack of examples in the official docs that are complete enough to work. For example:

import "github.com/stephenafamo/bob/dialect/psql/sm"
cte := psql.Select(
    sm.From("users"),
    sm.Where(psql.Quote("age").GTE(psql.Arg(21))),
)
...

This doesn't work for a number of reasons:

• It's missing the import for psql
• In order to do anything with cte you need to assemble it with other things
• Even if you take the rest of the example and assemble it with more stuff, those things can't be easily coerced into a string, so developers can't build toy programs for debugging.

Additionally, because the documentation is a bunch of disconnected go code snippets inside a Docusaurus website the code tends to be unmaintained and several examples don't work as written.

It's also very, very difficult to figure out the types of various things and how the types relate.

On the opposite end, there are so few comments and so much work with generics that running godoc on the codebase helps very little.

I've started a project to convert the existing Docusaurus webpage into content in the code that is extracted by godoc. Additionally, I'm making a new dialect that exists only to leverage go testable examples. It allows for stuff like this:

func ExampleSelect() {
    fmt.Print(example.Select(sm.Columns("col")).String())
    // Output: SELECT col
}

This is run during the unit tests, and shows up in godoc.

I'd like to know if this is the sort of thing that would be interesting for me to contribute back to this project, and if there's any feedback on the approach.

[stephenafamo]

I know that documentation is a weak spot for Bob, and I never seem to have enough time to dedicate to improving it.
I really appreciate any improvements, especially when it is made in a way that is easy to maintain.

Feel free to contribute this.