Query docs

[LouisGariepy]

Right now there's no way for users to add doc comments to their queries. We should make it possible to document queries from the SQL-side. For example:

--! universe
--? Select everything in the universe.
select * from Universe;

There are two outstanding questions with this:

1. Syntax: is --? OK? How do we handle multiline docs? does the order of annotations matter (i.e. should --? go before or after --!, does it even matter)?
2. What generated item should the docs apply to? The statement struct? the query struct? the query function?

Another related idea is to add auto-generated docs for some generated items like params structs. Something like /// This is the parameter struct for such_query

[Virgiel]

How about:

-- File comment (ignored)

--! universe
-- Universe comment
-- Over multiple line
select * from Universe;

[LouisGariepy]

Looks good to me!

[ricardodarocha]

I think it could follow Rust docs patterns. And generate the docstrings in generated rust code too. https://doc.rust-lang.org/rust-by-example/meta/doc.html

Actually the focus here is the rust code, not the sql. (My opinion)

[jacobsvante]

What about adding a third dash? E.g --- This is a doc comment.

That way there would be a kind of symmetry with the triple slash for standard doc strings.

[LouisGariepy]

@ricardodarocha That's the goal! Write documentation on SQL that will be converted to rust doc comments at codegen. This gives better IDE support and makes it possible to generate rust API docs for your queries.

@jacobsvante I like this idea!