Fixes #165 - Enable documentation comment validation in swift-format

[PARAIPAN9]

Motivation

This is for better documentation
Fixes #165

Modifications

Enabled some rules in .swift-format

Result

The .swift-format will be changed and the rules will reflect into the project

Test Plan

Run tests and CI

[czechboy0]

Sorry if the issue wasn't clear, part of the enablement will likely need to be to actually update all the places where the docs aren't passing validation. Otherwise our CI would go red.

[PARAIPAN9]

There is also this rule: BeginDocumentationCommentWithOneLineSummary that is comment related, currently set to false.

[czechboy0]

This will need updating the actual places missing docs (try running ./scripts/soundness locally). That might be quite a bit of work, so if that seems like too much, feel free to put the issue back into the queue and someone else will pick it up later.

[czechboy0]

There is also this rule: BeginDocumentationCommentWithOneLineSummary that is comment related, currently set to false.

I don't think we need to set that, it's overly strict about the abstract of each symbol. Could be added later.

[czechboy0]

Just setting the PR back to draft to communicate its status.

[PARAIPAN9]

Just a heads up to let you know that I'm still working on it, it will take a little bit of time.

[czechboy0]

No rush, @PARAIPAN9 – thanks 🙏

[PARAIPAN9]

Hello, I have another update about this PR. I've come to a stage where I need to include comment documentation for the generated files and by doing this there is reference test that is failing. What would be the best approach here? Should I modify the generator to produce the documentation, similar to how it does it for "Remark" comments?

[czechboy0]

No, let's exclude the files from being reformatted and linted. They get formatted as part of the generation process anyway, so this doesn't remove any value.

I suspect updating the script for formatting should do the trick.

[czechboy0]

@PARAIPAN9 Once you'd like this reviewed, please move the PR into Ready for review.

[PARAIPAN9]

Hello @czechboy0, I will update the branch and after I will also change the status.

[czechboy0]

Just one question about the script, otherwise looks great, thank you!

[czechboy0]

Thank you, @PARAIPAN9!

[czechboy0]

@PARAIPAN9 If you'd be interested, it'd be good to get this change into swift-openapi-runtime (and the urlsession/ahc transports) as well, but no pressure 🙂

[PARAIPAN9]

Sure, no problem!!