On wit sintax: formalizing documentation comments? #117
Description
Hi there!
Thank you for the good work!
I read #108 and @sunfishcode mentioned there is interest in feedback on the current wit sintax.
I wanted to ask about comment in wit sintax:
Should there be documentation and code comments?
Current state
While trying out wit-bindgen, I noticed that the code generation for Markdown passes comments as documentation, which is really nice! The online demo accepts both // and /// for (documentation) comments when generating the .md file.
I really like the current behaviour: taking comments before an item as its documentation.
As an example of what I would write and use the Markdown generated file as documentation:
/// person represents a physical, real person
record person {
/// Legal name of the person
name: string,
/// Year of bird
year: u32,
// TODO: add more fields as they are needed
}
// This comment does not appear in the md file generated because there is no element that follows
/// Returns the greeting we shoud use with `person`.
hello: function(who: person) -> string"Use case"
For now, .wit files are expected to be small(?) so this difference is not really needed. But if they get bigger and more complex, this differentiation of comments might come in handy :)
Currently, "code comments" can be achieved by adding a new line after them: no element follows this comment, so they are not passed to the .md file. But maybe this behaviour of the wit-bindgen-gen-markdown should be included in the wit syntax?