Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

misc: Improve TwiML XML Docs #681

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

Swimburger
Copy link
Contributor

@Swimburger Swimburger commented May 24, 2023

All third-party contributors acknowledge that any contributions they provide will be made under the same open-source license that the open-source project is provided under.

Fixes

Code generated from internal tool. Creating this as a draft, as the previous PRs were reverted and this generated code contains the same reverted code generation.

I dug into this mainly because of the numerous warning of incorrect XML docs when building this solution.
The main issue was the contents of the XML docs wouldn't be XML escaped, and any documentation related to TwiML would often embed XML inside XML Docs.
This issue has been resolved by XML escaping the contents.

Other optimizations:

  • File header should use // not ///
  • No unnecessary leading spaces
  • Write short docs on a single line, but long docs on multiple lines
  • Add line between properties
  • remove '-' and ':' from parameter name doc to match parameter name

This reduces the # of warnings from 1447 to 1223. Since this XML doc change is only applied to TwiML, the API XML docs generated from OpenAPI may still have similar issues.

Checklist

  • I acknowledge that all my contributions will be made under the project's license
  • I have made a material change to the repo (functionality, testing, spelling, grammar)
  • I have read the Contribution Guidelines and my PR follows them
  • I have titled the PR appropriately
  • I have updated my branch with the main branch
  • I have added tests that prove my fix is effective or that my feature works
  • I have added the necessary documentation about the functionality in the appropriate .md file
  • I have added inline documentation to the code I modified

@Swimburger Swimburger marked this pull request as ready for review July 10, 2023 14:20
@Swimburger
Copy link
Contributor Author

C'mon Twilio folks, this code contribution has been ready to merge on the internal repo and public repo for 6 months. The longer you let these things rot, the more conflicts will arise.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant