Function documentation and documentation generation

[vanillajonathan]

Looking at a function's signature doesn't always tell you everything, and you shouldn't have to read the code inside a function to grasp what it does, that is just an implementation detail. Documentation rocks!

The # is used for comments, so ## could be used for documentation.

There could be a community document that recommends a certain documentation style, for example Markdown.

Example:

## Adds two numbers together.
##
## Args:
##   a: The first number, an integer.
##   b: The second number, an integer.
##
## Returns:
##   The sum of `a` and `b` added together.
func add a b -> a + b

This would open the door for documentation generators.

$ prql-documentation-generator --format=html example.prql
Generated example.html

<h1>Documentation</h1>

<h2>Functions</h2>
Functions:
<ul>
  <li><a href="#fn-add">add</a> - Adds two numbers together.</li>
</ul>

<section>
  <h3 id="fn-add">add</h3>
  <p>Adds two numbers together.</p>
  <h4>Parameters</h4>
  <ul>
    <li><var>a</var> - The first number, an integer.</li>
    <li><var>b</var> - The second number, an integer.</li>
  </ul>
  <h4>Returns</h4>
  <p>The sum of <var>a</var> and <var>b</var> added together.</p>
</section>

Related issue: #730

[max-sixty]

+1 from me. This would become more helpful when we can do imports.

I'm fine with the ## syntax; coudl also use #! or something less block-y.

[aljazerzen]

I've missed this, but am all for it.

On the last dev call we discussed that we should split book into "tutorials" and "reference". The "reference" part should also document how all functions is std work, which would be best to do in doc comments directly in the std.prql.

Regarding the syntax: we don't have much options. It should probably start with # since // is used for integer division.

I think we should reserve #! to be used to document parent declaration scope.

Thus we land on ## for documenting next declaration (next variable). I don't think clash with markdown titles is too bad.

[snth]

I'm just checking https://doc.rust-lang.org/reference/comments.html for comparisons and standards.

What about 3 symbols which plus a space gives you a 4 spaces alignment?

Also, are we going to add block comments as well?

# Simple comment - single line

### Doc comment - single line

#* Simple comment - multi-line block 
    
    Unconventional so perhaps the following would be better?
 *#

#{ Simple comment - multi-line block 
    
    Is this better?
 }#

##* Doc comment - multi-line block

    This ?
*##

##{ Doc comment - multi-line block

    Or this?
}##

[aljazerzen]

Languages usually have a few different styles for the comments and I'm not sure why.

When I read the examples for all of the proposed block comments, I cannot easily parse it as a block. Could we keep things simple?

# simple comment, can go anywhere

#! Doc comment, documenting current module, spanning
#! multiple
#! lines.

## Doc comment, documenting the next variable
## declaration. If the associated variable cannot be found,
## this will trigger a parser error.
## In this case, this is variable named `a`
let a = (...)

I don't think we need block comments, as modern editors have the ability to insert ## when pressing enter within a comment and the ability to comment multiple lines.

[vanillajonathan]

The # is popular as a comment because of its use in Unix shells and web servers which let you execute CGI scripts written in languages like Perl, Python and Ruby.

So I think using #{ or #* for block comments would be bad because the lines between the first and last comment wouldn't really be comments.

I agree with @aljazerzen that block comments might not be needed, and I think #! and ## seem like good candidates for comments.

It would be good if you could use Markdown for the comments, such as.

#! Reverses a string.
#!
#! # Example
#! ```
#! let temp = reverse "Hello"
#! ```

[max-sixty]

I don't think we need block comments, as modern editors have the ability to insert ## when pressing enter within a comment and the ability to comment multiple lines.

Agree!