Doxygen Work Tracking Issue

[lundinc2]

Security issue notifications

If you discover a potential security issue in s2n we ask that you notify
AWS Security via our vulnerability reporting page. Please do not create a public github issue.

Problem:

We need to introduce doxygen to s2n-tls to create standardized documentation for the public API.

Resolves

• Add Inline Doxygen Documentation #439
• Enforce that every API in s2n.h is Present in the Usage Guide Docs #720

Solution:

• Add a doxygen config
• Add doxygen to s2n.h
• Add a doxygen CI job
• Resolve doxygen warnings for s2n.h
• Updated doxygen CI job to fail when a doxygen warning is introduced
• Add doxygen output to gh-pages branch
• Consider adding doxygen to release script, and push doxygen artifacts with release
• Prettify doxygen output by updating layout.xml and CSS
• Create a task to trim function definitions from USAGE_GUIDE.md

• Does this change what S2N sends over the wire? If yes, explain.
  No
• Does this change any public APIs? If yes, explain.
  No
• Which versions of TLS will this impact?
  No

Requirements / Acceptance Criteria:

What must a solution address in order to solve the problem? How do we know the solution is complete?

• RFC links: Links to relevant RFC(s)
• Related Issues: Link any relevant issues
• Will the Usage Guide or other documentation need to be updated?
• Testing: How will this change be tested? Call out new integration tests, functional tests, or particularly interesting/important unit tests.
  • Will this change trigger SAW changes? Changes to the state machine, the s2n_handshake_io code that controls state transitions, the DRBG, or the corking/uncorking logic could trigger SAW failures.
  • Should this change be fuzz tested? Will it handle untrusted input? Create a separate issue to track the fuzzing work.

Out of scope:

Is there anything the solution will intentionally NOT address?

[lundinc2]

We've opted to not include the doxygen output in the release artifacts for now. If this turns out to be a priority we will address it then.

[zaherd]

All tasks are done