Doc comments

[john-h-kastner-aws]

Rendered

[max2me]

LGTM. I'm especially excited about support for doc comments in JSON policy format.

[cdisselkoen]

LGTM, with the caveat below about considering all of our syntax options

[cdisselkoen]

what about before principal and resource in an appliesTo block?

(I do acknowledge the comment in Drawbacks that we need not block this RFC on discussing additional positions for doc comments, and additional ones can be added later as a non-breaking change. We can punt on my comment here if we want.)

[john-h-kastner-aws]

These would also be good additions. I wasn't sure where to draw the line for what to include in this RFC. Hopefully extra comments positions can be added later without another RFC.

[cdisselkoen]

I agree that we should consider all of these options; I'd like to hear others' thoughts on this.

[john-h-kastner-aws]

@philhassey suggests just using // as in Godoc which I hadn't considered as an option. Not a huge fan, but it's worth considering.

[khieta]

No strong feelings on my end. I like the look of ///, but likely I'm biased from having mostly used Rust lately. My second preference would be //@ (or some other third character like ! or #).

[philhassey]

In go doc comments are just comments // that are before an identifier. So fairly similar to the /// approach. Here's a link to the doc to read about it.

https://go.dev/blog/godoc

Here's an excerpt:

The convention is simple: to document a type, variable, constant, function, or even a package, write a regular comment directly preceding its declaration, with no intervening blank line. Godoc will then present that comment as text alongside the item it documents.

// Fprint formats using the default formats for its operands and writes to w.
// Spaces are added between operands when neither is a string.
// It returns the number of bytes written and any write error encountered.
func Fprint(w io.Writer, a ...interface{}) (n int, err error) {

[john-h-kastner-aws]

I'm not a fan of using // for doc comments and regular comments. Feels like it could make parsing a pain, and it would be easy to misplace a doc comment without an way for the parser to notice and warn you.

[khieta]

I'd also prefer a different syntax for doc comments vs. normal comments. Otherwise the two will only be distinguished by location in the policy/schema, which might make it difficult to figure out why a comment is (or isn't) rendering in the auto-generated documentation.

[hakanson]

I saw it referenced but can you add the link to Rust Doc comments in the RFC. C# also uses /// for Documentation comments

[khieta]

I'm happy with the proposal as-is (although I left some small comments).

[khieta]

I'd also prefer a different syntax for doc comments vs. normal comments. Otherwise the two will only be distinguished by location in the policy/schema, which might make it difficult to figure out why a comment is (or isn't) rendering in the auto-generated documentation.

[khieta]

This is an interesting option to me, but I still prefer the look of /// (or whatever syntax is chosen). I think it's fine to allow some overlap in functionality between annotations and doc comments. It might also be useful to unify their implementation in the future so that /// is syntactic sugar for @doc(...).

[john-h-kastner-aws]

Yes. The doc comment syntax being syntactic sugar under the hood is something I had in mind while writing this. It requires a substantial extension to extensions beyond ever RFC #48, but perhaps people will find other application of generalized annotations.

[john-h-kastner-aws]

We've tagged this as archived because we think that doc-comments should sugar for @doc annotations regardless of what the doc-comment syntax is. We plan to first extend where annotations can be placed (do be determined based on the outcome of rfc #48). After that documentation tooling can be developed against the annotation API. We can then re-examine this RFC to introduce syntactic sugar for doc comments.