Generate documentation of SQL tables #1623
Conversation
| id "The ID of the service deployment.": DataType::LargeUtf8, | ||
| ty "The type of the endpoint. Either `http` or `lambda`.": DataType::LargeUtf8, | ||
| endpoint "The address of the endpoint. Either HTTP URL or Lambda ARN.": DataType::LargeUtf8, | ||
| created_at "Timestamp indicating the deployment registration time.": DataType::Date64, |
There was a problem hiding this comment.
The syntax adds a lot of inline noise. Maybe an alternative is to move this to be a comment on every field instead.
There was a problem hiding this comment.
I like this idea. It is a bit similar to how clap does it for the command line options, right?
There was a problem hiding this comment.
Initially I thought this was not possible, that's why i went with the string literal. But this article https://stackoverflow.com/questions/53890817/macro-rule-for-matching-a-doc-comment has a solution for it, let me test this solution and get back to that.
There was a problem hiding this comment.
I will try to finish this PR while slinkydeveloper is on vacation to avoid PR rot.
|
I've pushed an update to incorporate @AhmedSoliman's idea to use Rust docs instead. |
| key: DataType::LargeUtf8, | ||
|
|
||
| /// Only contains meaningful values when a service stores state as `utf8`. This is the case for |
|
Looks a lot better. The only thing I'd suggest (potentially for a future PR) is to consider an alternative to the match per table name when generating the docs. |
To test it: `cargo xtask generate-table-docs` Unrelated fix to some dependencies that broke my build locally. Use Rust doc for documenting DF table schemas
Good point. I'll look whether there is an easy solution for it. |
|
I briefly looked into using linkme or inventory for automatically register the different table schemas at compile/before |
This commit changes the place where the table docs need to be registered to be included in the automatic table docs generation to a single place.
This commit updates the sql table column descriptions wrt feedback from restatedev/documentation#422.
Fix #980