From 098861b0ab6aaba41b12ee9cc6697a9ebfd4d240 Mon Sep 17 00:00:00 2001 From: "github-merge-queue[bot]" Date: Tue, 25 Jun 2024 13:01:29 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20@=20p4lang/p?= =?UTF-8?q?4c@0e1091b6f4697b0b8c0e96ca9038a438769c52d4=20=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- md__2home_2runner_2work_2p4c_2p4c_2docs_2_r_e_a_d_m_e.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/md__2home_2runner_2work_2p4c_2p4c_2docs_2_r_e_a_d_m_e.html b/md__2home_2runner_2work_2p4c_2p4c_2docs_2_r_e_a_d_m_e.html index 81d74dfd12..b181ea78eb 100644 --- a/md__2home_2runner_2work_2p4c_2p4c_2docs_2_r_e_a_d_m_e.html +++ b/md__2home_2runner_2work_2p4c_2p4c_2docs_2_r_e_a_d_m_e.html @@ -197,7 +197,8 @@

Writing documentation

Documenting the workings of the compiler is a never-ending (many times overlooked) job. We can always write better documentation!

-

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.

+

In P4C, documentation is generated using Doxygen. The generated documentation depends on Doxygen Awesome CSS. The documentation is dynamically updated and deployed on GitHub Pages.

+

There are two main sources from which we generate documentation: comments in the code and markup documents in the docs/doxygen directory.

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.

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.