Release 1.3.0

hdoc · Jul 22, 2022 · b710909 · b710909
1 parent fc0e872
commit b710909
Show file tree

Hide file tree

Showing 40 changed files with 2,266 additions and 1,771 deletions.
diff --git a/.hdoc.toml b/.hdoc.toml
@@ -1,6 +1,6 @@
 [project]
 name = "hdoc"
-version = "1.2.4"
+version = "1.3.0"
 git_repo_url = "https://github.com/hdoc/hdoc/blob/master/"
 
 [paths]

diff --git a/assets/search.js b/assets/search.js
@@ -78,17 +78,21 @@ function updateSearchResults() {
 
     res.forEach(function(obj){
         var a = document.createElement("a");
-        a.classList.add('list-item');
+        a.classList.add('panel-block');
         a.classList.add('is-family-code');
 
-        // Method, class, struct, or union
-        if (obj.type === 0 || obj.type === 2 || obj.type === 3 || obj.type === 4) {
-            a.setAttribute("href", "r" + obj.id + ".html");
+        // Method
+        if (obj.type === 0) {
+            a.setAttribute("href", "r" + obj.id);
         }
         // Function
         if (obj.type === 1) {
             a.setAttribute("href", "f" + obj.id + ".html");
         }
+        // Class, struct, or union
+        if (obj.type === 2 || obj.type === 3 || obj.type === 4) {
+            a.setAttribute("href", "r" + obj.id + ".html");
+        }
         // Enum or enum val
         if (obj.type === 5 || obj.type === 6) {
             a.setAttribute("href", "e" + obj.id + ".html");
@@ -98,9 +102,11 @@ function updateSearchResults() {
         span.classList.add("tag");
         span.classList.add("is-dark");
         span.classList.add("is-family-sans-serif");
+        span.classList.add("mr-2");
         span.textContent = typeIntToStr(obj.type);
 
         var decl = document.createElement("strong");
+        decl.classList.add("has-text-link");
         decl.textContent = " " + obj.decl;
 
         a.appendChild(span);

diff --git a/assets/styles.css b/assets/styles.css
diff --git a/flake.lock b/flake.lock
diff --git a/meson.build b/meson.build
@@ -1,4 +1,4 @@
-project('hdoc', 'cpp', version: '1.2.4', default_options: ['cpp_std=c++17', 'warning_level=3'])
+project('hdoc', 'c', 'cpp', version: '1.3.0', default_options: ['cpp_std=c++17', 'warning_level=3'])
 
 dep_llvm = dependency('LLVM', include_type: 'system')
 clang_modules = [
@@ -94,5 +94,6 @@ test_src = [
   'tests/index-tests/test-comments-functions.cpp',
   'tests/index-tests/test-comments-enums.cpp',
   'tests/index-tests/test-comments-namespaces.cpp',
+  'tests/index-tests/test-comments-templates.cpp',
 ]
 executable('index-tests', sources: test_src, dependencies: libdeps, cpp_args: '-DHDOC_TEST_CODE')
diff --git a/site/config.toml b/site/config.toml
@@ -10,4 +10,4 @@ build_search_index = false
 [markdown]
 # Whether to do syntax highlighting
 # Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola
-highlight_code = true
+highlight_code = false
diff --git a/site/content/docs/features/api-docs.md b/site/content/docs/features/api-docs.md
@@ -27,6 +27,7 @@ For functions and methods:
 - `@brief`
 - `@param`
 - `@returns`
+- `@tparam`
 
 For classes, structs, and unions:
 - `@brief`

diff --git a/site/content/release-notes.md b/site/content/release-notes.md
@@ -6,6 +6,20 @@ date = 2020-01-01
 description = "What's changed between each release of hdoc, including new features, fixes, and improvements."
 +++
 
+# Version 1.3.0 (21 July 2022)
+
+## New Features
+* hdoc now supports the `@tparam` command, which has the same semantics as it does in Doxygen.
+* hdoc now has a dark mode that automatically adapts to the user's system settings.
+* Documentation generated by hdoc will now have a small permalink icon at the relevant headers in the documentation to make it easier to share links to specific symbols.
+
+## Fixes
+* A bug where links to member functions on the documentation search page would lead to the wrong link has been fixed.
+  - Thank you [@jtbandes](https://github.com/jtbandes) for reporting [this issue](https://github.com/hdoc/hdoc/issues/14) and supplying reproduction steps.
+
+## Internal Changes
+* Updated to LLVM 14.
+
 # Version 1.2.4 (6 June 2022)
 
 This is a hotfix release.

diff --git a/site/static/header.png b/site/static/header.png
diff --git a/site/static/img/arch-dark.png b/site/static/img/arch-dark.png
diff --git a/site/static/img/arch.png b/site/static/img/arch.png
diff --git a/site/static/img/header-dark.png b/site/static/img/header-dark.png
diff --git a/site/static/img/header.png b/site/static/img/header.png
diff --git a/site/static/img/math-dark.png b/site/static/img/math-dark.png
diff --git a/site/static/img/math-original.png b/site/static/img/math-original.png
diff --git a/site/static/img/math.png b/site/static/img/math.png
diff --git a/site/static/img/oss-dark.png b/site/static/img/oss-dark.png
diff --git a/src/frontend/Frontend.cpp b/src/frontend/Frontend.cpp
@@ -160,8 +160,8 @@ hdoc::frontend::Frontend::Frontend(int argc, char** argv, hdoc::types::Config* c
     llvm::Optional<llvm::StringRef>    redirects[]   = {llvm::None, {"/dev/null"}, {tempFile}}; // stdin, stdout, stderr
 
     std::string errMsg = "";
-    if (int rc =
-            llvm::sys::ExecuteAndWait(compilerPath.get(), compilerFlags, llvm::None, redirects, 10, 0, &errMsg) != 0) {
+    int rc = llvm::sys::ExecuteAndWait(compilerPath.get(), compilerFlags, llvm::None, redirects, 10, 0, &errMsg);
+    if (rc != 0) {
       spdlog::error("Failed to determine the system include paths ({}, {}).", rc, errMsg);
       return;
     }

diff --git a/src/indexer/MatcherUtils.cpp b/src/indexer/MatcherUtils.cpp
@@ -126,37 +126,65 @@ bool isInAnonymousNamespace(const clang::Decl* d) {
   return false;
 }
 
-std::string getFunctionSignature(hdoc::types::FunctionSymbol& f, const clang::FunctionDecl* decl) {
-  std::string       signature;
-  static const auto printingPolicy = decl->getASTContext().getLangOpts();
+std::string getRecordProto(const hdoc::types::RecordSymbol& c) {
+  std::string proto;
+  if (c.templateParams.size() > 0) {
+    std::size_t count = 0;
+    proto += "template <";
+    for (const auto& tparam : c.templateParams) {
+      if (count > 0) {
+        proto += ", ";
+      }
+      if (tparam.templateType == hdoc::types::TemplateParam::TemplateType::TemplateTypeParameter) {
+        proto += tparam.isTypename ? "typename" : "class";
+        proto += tparam.isParameterPack ? "... " : " ";
+        proto += tparam.name;
+        // Get default argument if it exists
+        proto += tparam.defaultValue.size() > 0 ? " = " + tparam.defaultValue : "";
+      } else if (tparam.templateType == hdoc::types::TemplateParam::TemplateType::NonTypeTemplate) {
+        proto += tparam.type;
+        proto += tparam.isParameterPack ? "..." : "";
+        proto += " " + tparam.name;
+        // Get default argument if it exists
+        proto += tparam.defaultValue.size() > 0 ? " = " + tparam.defaultValue : "";
+      } else if (tparam.templateType == hdoc::types::TemplateParam::TemplateType::TemplateTemplateType) {
+        proto += tparam.type;
+        proto += tparam.isParameterPack ? "..." : "";
+        proto += " " + tparam.name;
+      }
+      count++;
+    }
+    proto += "> ";
+  }
+  proto += c.type + " " + c.name;
+  return proto;
+}
 
-  // Print template specifier
-  if (clang::FunctionTemplateDecl* templateDecl = decl->getDescribedFunctionTemplate()) {
+std::string getFunctionSignature(hdoc::types::FunctionSymbol& f) {
+  std::string signature;
+  if (f.templateParams.size() > 0) {
     uint64_t count = 0;
     signature += "template <";
-    for (const auto* parameterDecl : *templateDecl->getTemplateParameters()) {
+    for (const auto& tparam : f.templateParams) {
       signature += count > 0 ? ", " : "";
-      if (const auto* templateType = llvm::dyn_cast<clang::TemplateTypeParmDecl>(parameterDecl)) {
-        signature += templateType->wasDeclaredWithTypename() ? "typename" : "class";
-        signature += templateType->isParameterPack() ? "..." : "";
-        signature += " " + templateType->getNameAsString();
+      if (tparam.templateType == hdoc::types::TemplateParam::TemplateType::TemplateTypeParameter) {
+        signature += tparam.isTypename ? "typename" : "class";
+        signature += tparam.isParameterPack ? "..." : "";
+        signature += " " + tparam.name;
         // Get default argument if it exists
-        signature += templateType->hasDefaultArgument()
-                         ? " = " + templateType->getDefaultArgument().getAsString(printingPolicy)
-                         : "";
-      } else if (const auto* nonTemplateType = llvm::dyn_cast<clang::NonTypeTemplateParmDecl>(parameterDecl)) {
-        signature += nonTemplateType->getType().getAsString(printingPolicy);
-        signature += nonTemplateType->isParameterPack() ? "..." : "";
-        signature += " " + nonTemplateType->getNameAsString();
+        signature += tparam.defaultValue.size() > 0 ? " = " + tparam.defaultValue : "";
+      } else if (tparam.templateType == hdoc::types::TemplateParam::TemplateType::NonTypeTemplate) {
+        signature += tparam.type;
+        signature += tparam.isParameterPack ? "..." : "";
+        signature += " " + tparam.name;
         // Get default argument if it exists
-        signature += nonTemplateType->hasDefaultArgument()
-                         ? " = " + exprToString(nonTemplateType->getDefaultArgument(), printingPolicy)
-                         : "";
+        signature += tparam.defaultValue.size() > 0 ? " = " + tparam.defaultValue : "";
       }
       count++;
     }
     signature += ">";
   }
+
   f.postTemplate = signature.size();
 
   // Various qualifiers
@@ -298,6 +326,15 @@ void processRecordComment(hdoc::types::RecordSymbol&      cs,
         cs.briefComment = getCommentContents(commandComment, ctx);
       }
     }
+
+    if (const auto* tParamComment = llvm::dyn_cast<clang::comments::TParamCommandComment>(*c)) {
+      const std::string tParamName = tParamComment->getParamNameAsWritten().str();
+      for (auto& tparam : cs.templateParams) {
+        if (tparam.name == tParamName) {
+          tparam.docComment = getCommentContents(tParamComment, ctx);
+        }
+      }
+    }
   }
   hdoc::utils::rtrim(cs.briefComment);
   hdoc::utils::rtrim(cs.docComment);
@@ -351,6 +388,16 @@ void processFunctionComment(hdoc::types::FunctionSymbol&    f,
         }
       }
     }
+
+    if (const auto* tParamComment = llvm::dyn_cast<clang::comments::TParamCommandComment>(*c)) {
+      const std::string tParamName = tParamComment->getParamNameAsWritten().str();
+      for (auto& tparam : f.templateParams) {
+        if (tparam.name == tParamName) {
+          tparam.docComment = getCommentContents(tParamComment, ctx);
+        }
+      }
+    }
+
     // Look for \return, \returns, or \brief Doxygen commands
     if (const auto* commandComment = llvm::dyn_cast<clang::comments::BlockCommandComment>(*c)) {
       const std::string commandName = getCommandName(commandComment->getCommandID());

diff --git a/src/indexer/MatcherUtils.hpp b/src/indexer/MatcherUtils.hpp
@@ -23,7 +23,10 @@ bool isInIgnoreList(const clang::Decl*              d,
 bool isInAnonymousNamespace(const clang::Decl* d);
 
 /// @brief Update FunctionSymbol.proto with the full prototype
-std::string getFunctionSignature(hdoc::types::FunctionSymbol& f, const clang::FunctionDecl* function);
+std::string getFunctionSignature(hdoc::types::FunctionSymbol& f);
+
+/// @brief Get the full prototype for a record, including templates.
+std::string getRecordProto(const hdoc::types::RecordSymbol& c);
 
 /// @brief Convert a clang::Expr to a string, like clang::Decl->getNameAsString()
 std::string exprToString(const clang::Expr* expr, clang::PrintingPolicy printingPolicy);

diff --git a/src/indexer/Matchers.cpp b/src/indexer/Matchers.cpp
@@ -82,18 +82,41 @@ void hdoc::indexer::matchers::FunctionMatcher::run(const clang::ast_matchers::Ma
     }
     f.params.push_back(a);
   }
+
+  if (clang::FunctionTemplateDecl* templateDecl = res->getDescribedFunctionTemplate()) {
+    for (const auto* parameterDecl : *templateDecl->getTemplateParameters()) {
+      hdoc::types::TemplateParam tparam;
+      if (const auto* templateType = llvm::dyn_cast<clang::TemplateTypeParmDecl>(parameterDecl)) {
+        tparam.templateType    = hdoc::types::TemplateParam::TemplateType::TemplateTypeParameter;
+        tparam.isParameterPack = templateType->isParameterPack();
+        tparam.isTypename      = templateType->wasDeclaredWithTypename();
+        tparam.name            = templateType->getNameAsString();
+        tparam.defaultValue =
+            templateType->hasDefaultArgument() ? templateType->getDefaultArgument().getAsString(pp) : "";
+      } else if (const auto* nonTypeTemplate = llvm::dyn_cast<clang::NonTypeTemplateParmDecl>(parameterDecl)) {
+        tparam.templateType    = hdoc::types::TemplateParam::TemplateType::NonTypeTemplate;
+        tparam.isParameterPack = nonTypeTemplate->isParameterPack();
+        tparam.name            = nonTypeTemplate->getNameAsString();
+        tparam.defaultValue =
+            nonTypeTemplate->hasDefaultArgument() ? exprToString(nonTypeTemplate->getDefaultArgument(), pp) : "";
+        tparam.type = nonTypeTemplate->getType().getAsString(pp);
+      }
+      f.templateParams.push_back(tparam);
+    }
+  }
+
   const clang::comments::Comment* comment = res->getASTContext().getCommentForDecl(res, nullptr);
   if (comment != nullptr) {
     processFunctionComment(f, comment, res->getASTContext());
   }
 
-  // Don't print "void" return type for constructors and destructorss.
+  // Don't print "void" return type for constructors and destructors.
   f.isCtorOrDtor = clang::isa<clang::CXXConstructorDecl>(res) || clang::isa<clang::CXXDestructorDecl>(res);
   if (f.isCtorOrDtor == false) {
     f.returnType.name = res->getReturnType().getAsString(pp);
     f.returnType.id   = getTypeSymbolID(res->getReturnType());
   }
-  f.proto          = getFunctionSignature(f, res);
+  f.proto          = getFunctionSignature(f);
   f.isRecordMember = res->isCXXClassMember();
 
   findParentNamespace(f, res);
@@ -188,45 +211,44 @@ void hdoc::indexer::matchers::RecordMatcher::run(const clang::ast_matchers::Matc
     }
   }
 
+  // Determine record type
+  c.type = res->getKindName();
+
   // Get full declaration including templates
   clang::PrintingPolicy pp(res->getASTContext().getLangOpts());
-  std::size_t           count = 0;
   if (const auto* templateDecl = res->getDescribedClassTemplate()) {
-    c.proto += "template <";
     for (const auto* paramDecl : *templateDecl->getTemplateParameters()) {
-      if (count > 0) {
-        c.proto += ", ";
-      }
+      hdoc::types::TemplateParam tparam;
       if (const auto& templateType = llvm::dyn_cast<clang::TemplateTypeParmDecl>(paramDecl)) {
-        c.proto += templateType->wasDeclaredWithTypename() ? "typename" : "class";
-        c.proto += templateType->isParameterPack() ? "... " : " ";
-        c.proto += templateType->getNameAsString();
+        tparam.templateType    = hdoc::types::TemplateParam::TemplateType::TemplateTypeParameter;
+        tparam.isTypename      = templateType->wasDeclaredWithTypename();
+        tparam.isParameterPack = templateType->isParameterPack();
+        tparam.name            = templateType->getNameAsString();
         // Get default argument if it exists
-        c.proto += templateType->hasDefaultArgument() ? " = " + templateType->getDefaultArgument().getAsString(pp) : "";
-      } else if (const auto* nonTemplateType = llvm::dyn_cast<clang::NonTypeTemplateParmDecl>(paramDecl)) {
-        c.proto += nonTemplateType->getType().getAsString(pp);
-        c.proto += nonTemplateType->isParameterPack() ? "..." : "";
-        c.proto += " " + nonTemplateType->getNameAsString();
+        tparam.defaultValue =
+            templateType->hasDefaultArgument() ? templateType->getDefaultArgument().getAsString(pp) : "";
+      } else if (const auto* nonTypeTemplate = llvm::dyn_cast<clang::NonTypeTemplateParmDecl>(paramDecl)) {
+        tparam.templateType    = hdoc::types::TemplateParam::TemplateType::NonTypeTemplate;
+        tparam.type            = nonTypeTemplate->getType().getAsString(pp);
+        tparam.isParameterPack = nonTypeTemplate->isParameterPack();
+        tparam.name            = nonTypeTemplate->getNameAsString();
         // Get default argument if it exists
-        c.proto += nonTemplateType->hasDefaultArgument()
-                       ? " = " + exprToString(nonTemplateType->getDefaultArgument(), pp)
-                       : "";
+        tparam.defaultValue =
+            nonTypeTemplate->hasDefaultArgument() ? exprToString(nonTypeTemplate->getDefaultArgument(), pp) : "";
       } else if (const auto* templateTemplateType = llvm::dyn_cast<clang::TemplateTemplateParmDecl>(paramDecl)) {
-        c.proto +=
+        tparam.templateType = hdoc::types::TemplateParam::TemplateType::TemplateTemplateType;
+        tparam.type =
             clang::Lexer::getSourceText(clang::CharSourceRange::getCharRange(templateTemplateType->getSourceRange()),
                                         res->getASTContext().getSourceManager(),
                                         res->getASTContext().getLangOpts());
-        c.proto += templateTemplateType->isParameterPack() ? "..." : "";
-        c.proto += " " + templateTemplateType->getNameAsString();
+        tparam.name            = templateTemplateType->getNameAsString();
+        tparam.isParameterPack = templateTemplateType->isParameterPack() ? "..." : "";
       }
-      count++;
+      c.templateParams.push_back(tparam);
     }
-    c.proto += "> ";
   }
-  c.proto += res->getKindName().str() + " " + c.name;
 
-  // Determine record type
-  c.type = res->getKindName();
+  c.proto = getRecordProto(c);
 
   // TODO: fix this hack
   // If there is an anonymous struct/enum/union declared as a member variable of a record, clang

diff --git a/src/serde/CppReferenceURLs.hpp b/src/serde/CppReferenceURLs.hpp
@@ -9,7 +9,7 @@
 static const char* cppreferenceURL = "https://en.cppreference.com/w/cpp/";
 
 /// Map of std:: types to their cppreference.com URLs.
-/// The full URL is made by concating the value for a given key with cppreferenceURL.
+/// The full URL is made by concatenating the value for a given key with cppreferenceURL.
 static std::unordered_map<std::string, std::string> StdTypeURLMap = {
     {"std::array", "container/array"},
     {"std::vector", "container/vector"},
@@ -47,7 +47,6 @@ static std::unordered_map<std::string, std::string> StdTypeURLMap = {
     {"std::filesystem::recursive_directory_iterator", "filesystem/recursive_directory_iterator"},
     {"std::filesystem::file_status", "filesystem/file_status"},
     {"std::filesystem::space_info", "filesystem/space_info"},
-    {"std::filesystem::directory_entry", "filesystem/directory_entry"},
     {"std::filesystem::file_type", "filesystem/file_type"},
     {"std::filesystem::perms", "filesystem/perms"},
     {"std::filesystem::perm_options", "filesystem/perm_options"},