Remove legacy docs on controllers

[TarikGul]

Before we had the OpenAPI specs we would write the controller docs above the actual controller. Since we have more organized documentation within SwaggerAPI we no longer need them. This is also important to remove since it can be confusing for contributors or maintainers when adding features, or new endpoints.

@Imod7 Thoughts?

[Imod7]

Yes, I agree! I will open a PR (and link this issue) to remove the comments from all the controller files.

[Imod7]

@TarikGul I was looking at some of the controller files in order to remove all comments and I am seeing some parts that are not in the OpenAPI docs.

• For example, in the AccountsBalanceInfoController the docs related to :

  • The detailed explanation of the returned values and
  • The Substrate References

  are not present in the OpenAPI.

• Also, in other files there is other useful information that is also not present in OpenAPI. An example is in Staking Payouts.

Based on the above, in the comments of every controller I would opt for :

• Adding a reference to the OpenAPI specs in the comments of every controller
• Removing only the duplicate information compared to OpenAPI
• Add/keep any additional information that is not included in the OpenAPI specs

Also, have a clear guideline for the contributors on what they need to update and where regarding the docs. This I think should include also the copyright information.

@TarikGul wdyt ?