search

smithy-lang / smithy-dafny

Apache License 2.0
7 stars 8 forks source link

feat: Support @documentation (for Java initially) #463

Closed robin-aws closed 2 days ago

robin-aws commented 3 days ago

Issue #, if available: Resolves #427. Progresses on #359.

Description of changes: Adds a validator that any use of @documentation on local services does not use any CommonMark markup, and augments the Java code generation to recognize @documentation anywhere it currently recognized @javadoc.

Also adds a test model for validation and Java for now.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

robin-aws commented 2 days ago

We need at least one instance of the actual trait, instead of the /// short cut that I find... questionable...

The /// ... syntax is pure sugar for @documentation("..."), and by the time Smithy parses the model and gives it to us there's no difference. I can add at least one explicit @documentation trait just for completeness and help explain, but there's literally no difference in the model.

We can debate separately whether we want to use that syntax in our models. Personally I'd prefer it because it improves readability.

I'll also add background to the README.md (which I just realized I left out).