prql
prql copied to clipboard
PRQL
Doc comments
Followup for discussion #4110
Bottom line is that this will be the syntax for documentation comments:
-
#. doc commentfor the next statement -
#! doc commentfor the parent module -
@annotationfor the next statement -
@!annotationfor the parent statement
As with annotations, doc comments can attach to any statements (variables, types, modules) and will be available in the AST. We can make a tool that extracts this information and converts it to HTML, so it can be published somehow.
ATM, this would be most useful with std.prql module, which would benefit from exposing a bit more documentation (especially with arithmetic functions).
I would ask to refrain bike-shedding the syntax, unless there is a serious concern about usability.
I look forward to doc comments in the AST. I am working on some code to generate HTML documentation from a .prql file. I intend to integrate it with prqlc if that is okay.
Sure - depending on how it is written it could be maintained in this repo as well. Would you be up for doing it in rust?
Yes, it is written in Rust, and my intention is for it to be in this repo and part of the prqlc CLI tool.
part of the prqlc CLI tool
It will probably have a bunch of HTML-related dependencies that we probably don't as dependencies of the prqlc. Could it be a separate binary?
It will probably have a bunch of HTML-related dependencies that we probably don't as dependencies of the prqlc. Could it be a separate binary?
Yes, it could be a separate binary, however right now it doesn't have any dependencies at all, the HTML is just a string in Rust.
Like:
let mut html = String::new();
html.push_str("<html>");
html.push_str("</html>");
Ah, ok that makes sense - I like your approach of making the initial version simple before adding too much dependencies. It can easily be part of prqlc then! Do you need any help with integrating with prqlc CLI?
I created a PR at #4152, yes I would like some help integrating t with the prqlc CLI.