Skip to content

Commit

Permalink
Deploying to gh-pages from @ 0e1091b 🚀
Browse files Browse the repository at this point in the history
  • Loading branch information
github-merge-queue[bot] committed Jun 25, 2024
1 parent eec875f commit 098861b
Showing 1 changed file with 2 additions and 1 deletion.
3 changes: 2 additions & 1 deletion md__2home_2runner_2work_2p4c_2p4c_2docs_2_r_e_a_d_m_e.html
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,8 @@ <h1><a class="anchor" id="autotoc_md1"></a>
<h1><a class="anchor" id="autotoc_md3"></a>
Writing documentation</h1>
<p>Documenting the workings of the compiler is a never-ending (many times overlooked) job. We can always write better documentation!</p>
<p>In P4C, documentation is generated using Doxygen. There are two main sources from which we generate documentation: comments in the code and markup documents in the docs/doxygen directory.</p>
<p>In P4C, documentation is generated using Doxygen. The generated documentation depends on <a href="https://github.com/jothepro/doxygen-awesome-css">Doxygen Awesome CSS</a>. The documentation is dynamically updated and deployed on <a href="https://p4lang.github.io/p4c/">GitHub Pages</a>.</p>
<p>There are two main sources from which we generate documentation: comments in the code and markup documents in the docs/doxygen directory.</p>
<p>Code comments should capture the main intent of the implementation and the "why", rather than the "how". The how can be read from the code, however, documenting the reasons why a certain implementation was chosen will help other contributors understand the design choices and enable them to reuse your code. Also important in the context of the compiler is to document the invariants for each pass (or groups of passes), since it is likely that other developers will need to insert additional passes, and they should understand the effects that the pass ordering has on the AST.</p>
<p>Documentation in the markup documents is intended for higher level design documentation. The files will be automatically captured in the documentation in the order implied by their naming: XX_my_doc.md where XX is a number between 02-99. Currently, 00_revision_history.md contains the documentation revision history, and 01_overview.md is the overview of the compiler goals and architecture.</p>
<h2><a class="anchor" id="autotoc_md4"></a>
Expand Down

0 comments on commit 098861b

Please sign in to comment.