Add the XML Comment Documentation to the Server Project

[efonsecab]

In the project "FairPlaySocial.Server", enable the Documentation File

Once the documentation is enabled, fix all of the compilation errors by adding the respective XML comments.

[dsm637]

I would like to take this one

[efonsecab]

Hello @dsm637 , yes, you can go ahead and take this task. Please remember to use the development branch as a base when creating you local branch for this task

[dsm637]

Sure. I'm going to go through the Server project and add missing XML comments to classes, methods and parameters. Currently, enabling "Enable API documentation" produces about 100 errors. I presume that Swagger page also should work, correct?

[efonsecab]

Sure. I'm going to go through the Server project and add missing XML comments to classes, methods and parameters. Currently, enabling "Enable API documentation" produces about 100 errors. I presume that Swagger page also should work, correct?

Yes @dsm637 , that's right, the solution purposely handles warnings as errors to create compilation errors for these cases and make it easier to find where the missing comments are. Indeed, that is for seeing the documentation in the swagger page, you may not be able to load it until you fully configure your Development Environment with the multiple services secrets like Azure Text Analytics, Azure Translator, etc. We are in the process of making it easier for developers to fully configure their environments, for now, it is enough for the solution to compile once the comments have been added.

[dsm637]

There are bunch of auto-generated controllers (*g.cs). Is there a way to suppress the 1591 warning for them? Or there is a better way? One way is to update the FairPlaySocial.Server.Generators\ControllersIncrementalGenerator.cs to add pragme warning disabel 1591 in the file beginning. Also, there was mentioning on the GeneratedCode attribute but not sure if it's working. Alternatively, we could disable warnings on the project level and enable for specific files.

[efonsecab]

Hello @dsm637, I was expecting those not to cause issues. This is what can be done to avoid the autogenerated code to show errors In the project "FairPlaySocial.Server.Generators", file "ControllersIncrementalGenerator.cs", add the supress lines right before the namespace, and right before the line indicating the file name

pragma warning disable CS1591 // Missing XML comment for publicly visible type or member

pragma warning restore CS1591 // Missing XML comment for publicly visible type or member

That will cause the errors to disappear for the auto generated code. After the change, you may need to restart Visual Studio so these errors are not shown anymore

[efonsecab]

@all-contributors please add @dsm637 for code

[allcontributors[bot]]

@efonsecab

I've put up a pull request to add @dsm637! :tada: