address blog feedback, add diagrams

Author: evelez7

content/posts/2025-gsoc-clang-doc.md

@@ -8,8 +8,7 @@ title: "GSoC 2025: Improving Core Clang-Doc Functionality"
 I was selected as a contributor for GSoC 2025 under the project "Improving Core Clang-Doc Functionality" for LLVM.
 My mentors for the project were Paul Kirth and Petr Hosek.
 
-Clang-Doc is a tool in clang-tools-extra that generates documentation from Clang's AST.
-Clang-Doc can output documentation in Markdown, HTML, YAML, and JSON.
+Clang-Doc is a tool in clang-tools-extra that generates documentation from Clang's AST and can output Markdown, HTML, YAML, and JSON.
 The project started in 2018 but major development eventually slowed.
 Recently, there have been efforts to get it back on track.
 
@@ -26,7 +25,7 @@ The project idea proposed three main areas of focus to improve documentation qua
 First, not all C++ constructs were supported, like friends or concepts.
 Not supporting core C++ constructs in C++ documentation is not good.
 Second, it's important that Doxygen command support is robust and that we can support as many as possible.
-Third and last, having Markdown available to developers for documentation would be useful.
+Lastly, having Markdown available to developers for documentation would be useful.
 Markdown provides the power of expression in an area that is technically dense.
 It can be used to highlight critical information and warnings.
 
@@ -39,49 +38,75 @@ Here's a quick overview on Clang-Doc's architecture, which follows a map-reduce
 3. Once all source declarations are serialized, write them into bitcode, reduce, and read the reduced Infos.
 4. Serialize Infos into the desired format.
 
+<div style="margin:0 auto;">
+  <img src="/img/gsoc-2025-clang-doc-architecture.png"><br/>
+</div>
+
 It seems fairly straightforward, but the architecture had a critical flaw.
 If a new C++ construct needed to be supported, it would be visited and serialized, but then support would have to be added to each backend individually.
 If you wanted to serialize something in YAML, you'd have to implement the Markdown logic separately.
 This placed a very high maintenance cost for extending basic functionality, even if you just wanted to add something simple.
 It also easily led to generator disparity; a construct might be serialized in YAML, but not in Markdown.
-
 Testing was also in an awkward spot because it was unclear what format would be used to verify if the documentation output was acceptable.
-YAML was the initial candidate for this, but my mentors had started to consider JSON instead.
-Feature parity was far apart; some backends were tested for certain attributes that others didn't have.
 
 ## The Good: Mustache
 
 Last year's GSoC brought in great improvements that became the basis of my summer.
 First, last year's GSoC contributor landed a large performance improvement.
 I might not have been able to test Clang-Doc on Clang itself without it.
 
-Another contribution that was essential to my summer is the [Mustache template implementation](https://mustache.github.io/) in LLVM.
+Another contribution that was essential to my summer is the [Mustache template engine](https://mustache.github.io/) implementation in LLVM.
 Mustache templates allow Clang-Doc to shift away from manually generating HTML tags and eliminate high maintenance burdens.
 Templates could also solve the feature parity problem by using JSON to feed templates.
 
-
 # Building a JSON Backend
 
 While familiarizing myself with the codebase during the Community Bonding Period, I quickly determined that implementing a JSON backend would be incredibly beneficial to the project and my summer plans.
 A JSON backend presented two immediate benefits:
 
-1. We could use it to feed HTML Mustache templates and future template usage.
+1. We could use it to feed our Mustache HTML templates and future template usage.
 2. As the main feeder format, testing can be focused on the JSON output.
 
 The existing Mustache backend in Clang-Doc already contained logic to create JSON documents, but they were immediately discarded when the templates were rendered.
-I adapted most of the code into a separate generator to output JSON files and was able land it within two weeks.
-This ended up accelerating my work because I could implement support for C++ constructs and test them in JSON instead of another format that we would probably be refactoring in the near future.
+This backend is extremely beneficial to Clang-Doc because it would completely eliminate any need for manual HTML tag generation, thus greatly reducing lines of code.
+If the JSON and template rendering logic from the existing implementation were uncoupled, we could apply the same pattern to any format we'd want to support.
+For example, Markdown generation would be a similar case to HTML where templates would be used to automate the creation of all markup.
+
+<div style="margin:0 auto;">
+  <img src="/img/gsoc-2025-clang-doc-template-backend.png"><br/>
+</div>
+
+This diagram models the architecture that Clang-Doc would follow given a unified JSON backend.
+Note the similarities to Clang, where our frontend (the visitation/serialization) gathers all the information we need and emits an intermediate representation (JSON).
+The JSON is then fed to the desired templates to produce our documentation, similar to how IR is used for different LLVM backends.
+Following this pattern would reduce the logic maintenance to only the JSON generation; all the formatting for HTML, Markdown, etc. would exist in template files that are very simple to change.
+
+Thus, I adapted the JSON logic from the Mustache backend and create a separate JSON backend.
+I also added tests to ensure the C++ constructs that Clang-Doc already supported were properly serialized in JSON.
+I didn't realize it at the time, but this would end up dramatically accelerating my pace of implementation.
+
+## C++ Language Support and Testing
+
+After landing the JSON generator in about a week, I returned to my proposed schedule by implementing support for C++ constructs like friends.
+The new JSON generator allowed me to quickly implement and test these features because I didn't have to worry about HTML formatting or appearance.
+I could work with the assumption that as long as the information was properly serialized into JSON, it would be able to be displayed well in HTML later.
+
+Testing is an area that the JSON backend brought a lot of clarity to.
+Clang-Doc didn't have a format where all the information we wanted, like ensuring we document that a variable is `cosnt` or `volatile`, was validated.
+At one time, YAML was meant to be that format, but it suffered from feature disparity since it wasn't relevant when something needed to be displayed in HTML.
+I ended up adding 14 different test files over the course of the summer to ensure test coverage.
 
 ### Pull Requests
 - [add tags to Mustache namespace template](https://github.com/llvm/llvm-project/pull/142045)
-- [add namespaces](https://github.com/llvm/llvm-project/pull/142483)
+- [add a JSON generator](https://github.com/llvm/llvm-project/pull/142483)
+- [add namespaces to JSON generator](https://github.com/llvm/llvm-project/pull/143209)
 - [removed default label on some switches](https://github.com/llvm/llvm-project/pull/143919)
 - [precommit](https://github.com/llvm/llvm-project/pull/144160) and [add support for concepts](https://github.com/llvm/llvm-project/pull/144430)
 - [precommit](https://github.com/llvm/llvm-project/pull/145069) and [document global variables](https://github.com/llvm/llvm-project/pull/145070)
 - [refactor JSONGenerator array usage](https://github.com/llvm/llvm-project/pull/145595)
 - [refactor BitcodeReader::readSubBlock](https://github.com/llvm/llvm-project/pull/145835)
 - [serialize isBuiltIn and IsTemplate](https://github.com/llvm/llvm-project/pull/146149)
-- [precommit](https://github.com/llvm/llvm-project/pull/146164) and [friends](https://github.com/llvm/llvm-project/pull/146165)
+- [precommit](https://github.com/llvm/llvm-project/pull/146164) and [serialize friends](https://github.com/llvm/llvm-project/pull/146165)
 
 # Comments
 
@@ -126,6 +151,18 @@ After the change, Clang-Doc's comments were structured like this:
 
 Now, we can just iterate over every type of comment, which means iterating over every array.
 This left our JSON documentation with a few more fields, since one is needed for every Doxygen command, but with easier identification of what comments exist in the documentation.
+After this refactor was landed, I implemented support for the comments we had already supported and ones we didn't, like Doxygen code comments.
+
+## Reaping the benefits of JSON
+
+This was an area where a JSON backend once again accelerated my progress.
+Without it, I would've written the same JSON logic but would've had to written tests to check for the comments in HTML.
+This would've been incredibly cumbersome since I would've had to:
+
+1. Add the appropriate templating language to allow the comments to render.
+2. Add the correct HTML tags to allow the test to pass.
+
+Like I just mentioned, comments weren't being generated the best in HTML anyways, so I could've run into more annoyances if I had to follow that workflow.
 
 
 ### Pull Requests
@@ -139,6 +176,8 @@ This left our JSON documentation with a few more fields, since one is needed for
 - [remove nesting of text comments inside paragraphs](https://github.com/llvm/llvm-project/pull/150451)
 - [generate comments for functions](https://github.com/llvm/llvm-project/pull/150570)
 - [add param comments to comment template](https://github.com/llvm/llvm-project/pull/150571)
+- [add return comments to comment template](https://github.com/llvm/llvm-project/pull/150647)
+- [add code comments to comment template](https://github.com/llvm/llvm-project/pull/150648)
 
 # Markdown
 Markdown was the most speculative aspect of the project.
@@ -155,15 +194,39 @@ Without an out-of-the-box solution, we were left with implementing our own parse
 When I considered this in my proposal, I knew an in-tree parser would want to conform to the simplest possible standard.
 Markdown has no official standard, so I opted for CommonMark conformance.
 
-The summer ended without a complete solution since the a couple weeks were spent researching whether or not this could be integrated directly in the Clang comment parser or whether we'd need to build our own solution or not.
+The summer ended without a complete solution since a couple weeks were spent researching whether or not this could be integrated directly in the Clang comment parser or whether we'd need to build our own solution or not.
 You can see my initial draft [here](https://github.com/llvm/llvm-project/pull/155887).
 
+# Refactors, Name Mangling, and More!
+During my summer, I would stumble into places where I would think "This could be better" and my mentors usually agreed.
+Thus, there were a few patches where I dedicated time to general refactors to improve code reuse and hopefully make the lives of future contributors much easier than what I had to go through.
+In fact, one of my best refactors was of the JSON generator that I wrote, which my mentor noted had a lot of areas for great code reuse.
+Future me was extremely thankful for the easy-to-use functions I had added.
+I also refactored some of the bitcode reader/writer code so that less copy-pasting would be involved in the future.
+
+Another signifcant feature that I hadn't planned was name mangling.
+Clang-Doc suffered from a bug where template specializations would be serialized to the same file as their described class because they had the same name.
+The YAML backend avoided this problem because its filenames were SymbolIDs, but this meant that the lit tests would have to use regex to find the file for FileCheck.
+Nasty.
+In HTML, you ended up with a buggy HTML page from duplicate tags.
+In JSON, you get a fatal error since two JSON documents can't live in the same file.
+So I used `ItaniumMangleContext` to generate mangled names we could use for the filenames.
+
 # Overview
-I implemented a new JSON generator for Clang-Doc that will serve as the basis for documentation generation.
+I implemented a new JSON generator that will serve as the basis for Clang-Doc's documentation generation.
 This will vastly reduce overall lines of code and maintenance burdens.
+I added a lot of tests to increase code coverage and ensure we are serializing all the information necessary for high-quality documentation.
 I refactored our comment handling to streamline the logic that handles them and for better output in the HTML.
 I also explored options for rendering Markdown and began an implenetation for a parser that I plan on working on in the future.
-Along the way, I also did some refactoring to improve code reuse and improve contributor burden by reducing boilerplate code.
+Along the way, I also did some refactoring to improve code reuse and improved maintenance burdens by reducing boilerplate code.
+
+After my work this summer, Clang-Doc is nearly ready to switch to HTML generation via Mustache templates, which will be a huge milestone.
+It is backed by the JSON generator which will allow for a much more flexible architecture that will change how we generate other documentation formats like our existing Markdown backend.
+All of this was done with little to no performance loss.
+
+Another huge boon from my work this summer is that contributors should (hopefully) have a much easier time contributing to Clang-Doc.
+Before, the threshold for contributing was high due to a disjointed architecture.
+I hope that future contributors find Clang-Doc easier to navigate and to write helpful patches due to my work.
 
 Over the summer, I addressed these issues:
 - [template operator T() produces a bad name](https://github.com/llvm/llvm-project/issues/59812)
@@ -172,12 +235,13 @@ Over the summer, I addressed these issues:
 - [Add a JSON backend to clang-doc to better leverage mustache templates](https://github.com/llvm/llvm-project/issues/140094)
 
 # Future Work
+These are issues that I identified over the summer that I wasn't able to address but would benefit from community discussion and contribution.
 
 ## Doxygen Grouping
 
 Doxygen has a very useful [grouping](https://www.doxygen.nl/manual/grouping.html) feature that allows structures to be grouped under a custom heading or on separate pages.
 You can see it in [llvm::sys::path](https://llvm.org/doxygen/namespacellvm_1_1sys_1_1path.html).
-We [opened up an issue](https://github.com/llvm/llvm-project/issues/151184#issuecomment-3133596874) for Clang to track this issue, which ended up being a duplicate of [this issue](https://github.com/llvm/llvm-project/issues/123582).
+We [opened up an issue](https://github.com/llvm/llvm-project/issues/151184) for Clang to track this issue, which ended up being a duplicate of [this issue](https://github.com/llvm/llvm-project/issues/123582).
 
 There would most likely have to be some major changes to Clang's comment parsing and Clang's own parsing.
 That's because a lot of the group opening tokens in Clang are free-floating, like so: