Write out summary of documentation in docgen tool. (#5266)

3 files changed, 61 insertions, 0 deletions

diff --git a/source/slang/slang-doc-markdown-writer.cpp b/source/slang/slang-doc-markdown-writer.cpp
index 2d38703c7..2b4586db2 100644
--- a/source/slang/slang-doc-markdown-writer.cpp
+++ b/source/slang/slang-doc-markdown-writer.cpp
@@ -2728,6 +2728,63 @@ void DocumentPage::writeToDisk()
     writePageToDisk(this);
 }
 
+struct DocumentationStats
+{
+    int documentedPageCount = 0;
+    List<String> undocumentedPages;
+};
+
+static void _collectStats(DocumentationStats& stats, DocumentPage* page)
+{
+    if (!page->skipWrite && page->entries.getCount() != 0)
+    {
+        bool isDocumented = false;
+        for (auto entry : page->entries)
+        {
+            if (entry->m_markup.getUnownedSlice().trim().getLength() > 0)
+            {
+                DeclDocumentation doc;
+                doc.parse(entry->m_markup.getUnownedSlice());
+                auto desc = doc.sections.tryGetValue(DocPageSection::Description);
+                // A page is considered documented if it has a description section
+                // with more than 10 characters and ends with a `.`.
+                if (desc && desc->ownedText.trim().getLength() > 10 &&
+                    String(desc->ownedText.trim()).endsWith("."))
+                {
+                    isDocumented = true;
+                }
+                break;
+            }
+        }
+        if (isDocumented)
+        {
+            stats.documentedPageCount++;
+        }
+        else
+        {
+            stats.undocumentedPages.add(page->title);
+        }
+    }
+    for (auto child : page->children)
+    {
+        _collectStats(stats, child);
+    }
+}
+
+void DocumentPage::writeSummary(UnownedStringSlice fileName)
+{
+    DocumentationStats stats;
+    _collectStats(stats, this);
+    StringBuilder sb;
+    sb << "documented pages: " << stats.documentedPageCount << "\n";
+    sb << "undocumented pages: " << stats.undocumentedPages.getCount() <<"("
+        << String(stats.undocumentedPages.getCount() / (float)(stats.documentedPageCount + stats.undocumentedPages.getCount()) * 100, "%.1f")
+        << "%)\n\n";
+    for (auto page : stats.undocumentedPages)
+        sb << page << "\n";
+    File::writeAllText(fileName, sb.produceString());
+}
+
 DocumentPage* DocumentPage::findChildByShortName(const UnownedStringSlice& name)
 {
     for (auto child : children)
diff --git a/source/slang/slang-doc-markdown-writer.h b/source/slang/slang-doc-markdown-writer.h
index 813e674ae..20912af46 100644
--- a/source/slang/slang-doc-markdown-writer.h
+++ b/source/slang/slang-doc-markdown-writer.h
@@ -29,6 +29,9 @@ struct DocumentPage : public RefObject
     OrderedHashSet<ASTMarkup::Entry*> entries;
     ASTMarkup::Entry* getFirstEntry() { return *entries.begin(); }
     void writeToDisk();
+
+    // Write summary on number of documented entries.
+    void writeSummary(UnownedStringSlice fileName);
 };
 
 struct DocumentationConfig
diff --git a/source/slang/slang.cpp b/source/slang/slang.cpp
index 4bdbbd0aa..586a38b54 100644
--- a/source/slang/slang.cpp
+++ b/source/slang/slang.cpp
@@ -331,6 +331,7 @@ void Session::writeStdlibDoc(String config)
         auto rootPage = writer.writeAll(config.getUnownedSlice());
         File::writeAllText("toc.html", writer.writeTOC());
         rootPage->writeToDisk();
+        rootPage->writeSummary(toSlice("summary.txt"));
     }
     ComPtr<ISlangBlob> diagnosticBlob;
     sink.getBlobIfNeeded(diagnosticBlob.writeRef());