Ph0enixKM
[Feature] Comment doc block
So right now we have tons of function in stdlib.
Can be handy to document them in the file itself, in this way the documentation can generated aautomatically. So I was thinking something for that.
In Amber looking at the doc there is no way right now for commenting, so we need to choose what is the best way.
Rust uses /** like PHP (https://doc.rust-lang.org/reference/comments.html), python instead use """the sentence""".
i think we should use /// and /** */ for doc strings to be consistent with rust
also we should think through tags like this:
/**
@return It will return none if has failed
*/
async fn get_user() -> Option<User> { ... }
id say we go with these:
| tag | desc |
|---|---|
@return {desc} |
is used to describe a function's return value |
@param {paramName} {desc} |
is used to describe a function's param |
@author {name} |
is used to describe the author |
@license {SPDXID} |
to describe the license |
Seems the best way, maybe with https://docs.rs/comment-parser/latest/comment_parser/ we can implement easily?
At https://github.com/Ph0enixKM/Amber/pull/62 I used /// syntax for doc comments. We could use the @param etc. just like in JSDoc to document particular params and the return type. Not sure if @author and @license are necessary at this stage but yeah
Oh yeah we could add the /** */ syntax - I just forgot to add the multiline comments. I didn't the need to implement them - now it's the good time
If we will go on /** */ syntax we can approve? https://github.com/Ph0enixKM/Amber/pull/238
So in the way I will add all the comments in the stdlib
I think that also comments can include parameters.
I think that can be interesting define script parameters like wp-cli does in a comment: https://github.com/wp-cli/wp-cli/blob/main/php/commands/src/Help_Command.php#L9 In this way the help is automatic for the script but also improve the readability.
We have now documentation with \\\ and is not added in the bash file but with 2 ues