support source paths in Location objects

Location objects only contained the full path and the path relative to the search directories. This commit includes a new field for the source path, which contains the path relative to the `source-root`.

#feat

fix #798

Author: alandefreitas

CMakeLists.txt

@@ -440,7 +440,7 @@ if (MRDOCS_BUILD_TESTS)
             DEPENDS mrdocs.rnc)
         add_custom_target(mrdocs_rng ALL DEPENDS mrdocs.rng)
 
-        file(GLOB_RECURSE XML_SOURCES CONFIGURE_DEPENDS test-files/*.xml)
+        file(GLOB_RECURSE XML_SOURCES CONFIGURE_DEPENDS test-files/golden-tests/*.xml)
         add_test(NAME xml-lint
                  COMMAND ${LIBXML2_XMLLINT_EXECUTABLE} --dropdtd --noout
                      --relaxng ${CMAKE_CURRENT_BINARY_DIR}/mrdocs.rng ${XML_SOURCES}

docs/modules/ROOT/pages/generators.adoc

@@ -862,25 +862,25 @@ The location object has the following properties:
 |===
 |Property |Type| Description
 
-| `path`
+| `fullPath`
 | `string`
-| The path of the source file.
+| The full path of the source file.
 
-| `file`
+| `shortPath`
 | `string`
-| The filename of the source file.
+| The path of the source file relative to the search directories.
+
+| `sourcePath`
+| `string`
+| The path of the source file relative to the `source-root`.
 
 | `line`
 | `integer`
-| The line number of the symbol.
-
-| `kind`
-| `string`
-| The kind of file (e.g., `source`, `system`, `other`).
+| The line number of the symbol at this location.
 
 | `documented`
 | `bool`
-| Whether the symbol is documented.
+| Whether the symbol is documented at this location.
 |===
 
 [#tparam-fields]

docs/mrdocs.schema.json

@@ -225,7 +225,7 @@
     },
     "source-root": {
       "default": "<config-dir>",
-      "description": "Path to the root directory of the source code. This path is used as a default for input files and a base for relative paths formed from absolute paths.",
+      "description": "Path to the root directory of the source code. This path is used as a default for input files and a base for relative paths formed from absolute paths. This should typically be the root directory of the git project, as relative paths formed from it can be used to create links to these source files in the repository. Templates use the `base-url` option to create links to the source code.",
       "title": "Path to the root directory of the source code",
       "type": "string"
     },

include/mrdocs/Metadata/Source.hpp

@@ -51,11 +51,15 @@ struct MRDOCS_DECL
 {
     /** The full file path
     */
-    std::string Path;
+    std::string FullPath;
 
-    /** Name of the file
+    /** The file path relative to one of the search directories
     */
-    std::string Filename;
+    std::string ShortPath;
+
+    /** The file path relative to the source-root directory
+     */
+    std::string SourcePath;
 
     /** Line number within the file
     */
@@ -68,12 +72,14 @@ struct MRDOCS_DECL
     //--------------------------------------------
 
     Location(
-        std::string_view const filepath = {},
-        std::string_view const filename = {},
+        std::string_view const full_path = {},
+        std::string_view const short_path = {},
+        std::string_view const source_path = {},
         unsigned const line = 0,
         bool const documented = false)
-        : Path(filepath)
-        , Filename(filename)
+        : FullPath(full_path)
+        , ShortPath(short_path)
+        , SourcePath(source_path)
         , LineNumber(line)
         , Documented(documented)
     {
@@ -92,7 +98,7 @@ struct LocationEmptyPredicate
     constexpr bool operator()(
         Location const& loc) const noexcept
     {
-        return loc.Filename.empty();
+        return loc.ShortPath.empty();
     }
 };
 

mrdocs.rnc

@@ -326,7 +326,9 @@ grammar
     Location =
         element file
         {
-            attribute path {text},
+            # attribute full-path {text},
+            attribute short-path {text},
+            attribute source-path {text},
             attribute line {text},
             attribute class {"def"} ?,
             empty

share/mrdocs/addons/generator/common/partials/location/source.hbs

@@ -11,9 +11,9 @@
 
 --}}
 Declared in {{#>markup/code~}}
-    {{ str "<" }}{{#unless (and @root.config.base-url (eq dcl.kind "source"))~}}
-        {{dcl.file}}
+    {{ str "<" }}{{#if (and @root.config.base-url dcl.shortPath dcl.sourcePath)~}}
+        {{#>markup/a href=(concat @root.config.base-url dcl.sourcePath '#L' dcl.line)}}{{dcl.shortPath}}{{/markup/a}}
     {{~else~}}
-        {{#>markup/a href=(concat @root.config.base-url dcl.file '#L' dcl.line)}}{{dcl.file}}{{/markup/a}}
-    {{~/unless~}}{{ str ">" }}
+        {{dcl.shortPath}}
+    {{~/if~}}{{ str ">" }}
 {{~/markup/code}}

src/lib/AST/ASTVisitor.cpp

@@ -696,7 +696,7 @@ populate(
         {
             return;
         }
-        I.DefLoc.emplace(file->full_path, file->short_path, line, documented);
+        I.DefLoc.emplace(file->full_path, file->short_path, file->source_path, line, documented);
     }
     else
     {
@@ -705,13 +705,13 @@ populate(
             [line, file](const Location& l)
             {
                 return l.LineNumber == line &&
-                    l.Path == file->full_path;
+                    l.FullPath == file->full_path;
             });
         if (existing != I.Loc.end())
         {
             return;
         }
-        I.Loc.emplace_back(file->full_path, file->short_path, line, documented);
+        I.Loc.emplace_back(file->full_path, file->short_path, file->source_path, line, documented);
     }
 }
 
@@ -2762,6 +2762,15 @@ buildFileInfo(std::string_view const file_path)
         return tryGetRelativePosixPath(posixPrefix);
     };
 
+    // Populate file relative to source-root
+    if (files::isAbsolute(config_->sourceRoot))
+    {
+        if (auto shortPath = tryGetRelativePath(config_->sourceRoot))
+        {
+            file_info.source_path = std::string(*shortPath);
+        }
+    }
+
     // Find the best match for the file path in the search directories
     for (HeaderSearch& HS = sema_.getPreprocessor().getHeaderSearchInfo();
          DirectoryLookup const& DL : HS.search_dir_range())
@@ -2780,14 +2789,11 @@ buildFileInfo(std::string_view const file_path)
         }
     }
 
-    // Fallback to sourceRoot
-    if (files::isAbsolute(config_->sourceRoot))
+    // Fallback to the source root
+    if (!file_info.source_path.empty())
     {
-        if (auto shortPath = tryGetRelativePath(config_->sourceRoot))
-        {
-            file_info.short_path = std::string(*shortPath);
-            return file_info;
-        }
+        file_info.short_path = file_info.source_path;
+        return file_info;
     }
 
     // Fallback to system search paths in PATH

src/lib/AST/ASTVisitor.hpp

@@ -95,6 +95,9 @@ class ASTVisitor
         // The file path relative to a search directory.
         std::string short_path;
 
+        // The file path relative to the source-root directory.
+        std::string source_path;
+
         // Whether this file passes the file filters
         std::optional<bool> passesFilters;
     };

src/lib/Gen/xml/XMLWriter.cpp

@@ -626,10 +626,14 @@ XMLWriter::
 writeSourceInfo(
     SourceInfo const& I)
 {
-    if(I.DefLoc)
+    if (I.DefLoc)
+    {
         writeLocation(*I.DefLoc, true);
-    for(auto const& loc : I.Loc)
+    }
+    for (auto const& loc: I.Loc)
+    {
         writeLocation(loc, false);
+    }
 }
 
 void
@@ -639,9 +643,11 @@ writeLocation(
     bool def)
 {
     tags_.write("file", {}, {
-        { "path", loc.Filename },
+        // { "full-path", loc.FullPath },
+        { "short-path", loc.ShortPath },
+        { "source-path", loc.SourcePath },
         { "line", std::to_string(loc.LineNumber) },
-        { "class", "def", def } });
+        { "class", "def", def }});
 }
 
 //------------------------------------------------

src/lib/Lib/ConfigOptions.json

@@ -42,7 +42,7 @@
       {
         "name": "source-root",
         "brief": "Path to the root directory of the source code",
-        "details": "Path to the root directory of the source code. This path is used as a default for input files and a base for relative paths formed from absolute paths.",
+        "details": "Path to the root directory of the source code. This path is used as a default for input files and a base for relative paths formed from absolute paths. This should typically be the root directory of the git project, as relative paths formed from it can be used to create links to these source files in the repository. Templates use the `base-url` option to create links to the source code.",
         "type": "dir-path",
         "default": "<config-dir>",
         "relative-to": "<config-dir>",