[Bug] Exception while trying to parse <code> XML tags with source field defined.

[AlanSherba]

Describe the bug

I have a function with a <code> tag like so:

/// <summary>
/// ...
/// <code source="DataStoreExamples.cs"></code>
/// </summary>
DataStoreGetVariableRequest GetVariable(string key, object defaultValue);

When consuming the api docfx metadata docfx.json I get the following exception in the console:

ArgumentNullException: Value cannot be null. (Parameter 'path1')
  at void Throw(string paramName)                                               
  at string Combine(string path1, string path2)                                 
  at string <GetXmlCommentParserContext>g__ResolveCode|1(string source) in      
     SymbolVisitorAdapter.cs:722
 //etc

Which refers to this line:

//src/Docfx.Dotnet/ManagedReference/Visitors/SymbolVisitorAdapter.cs/ln722
var basePath = _config.CodeSourceBasePath ?? (
                item.Source?.Path is { } sourcePath
                    ? Path.GetDirectoryName(Path.GetFullPath(Path.Combine(EnvironmentContext.BaseDirectory, sourcePath)))
                    : null);

Aka EnvironmentContext.BaseDirector == null. But......

//src/Docfx.Plugins/EnvironmentContext.cs
public static string BaseDirectory => string.IsNullOrEmpty(_baseDirectory) ? "." : _baseDirectory;

It shouldn't be possible to be null???

Is this a bug? or do I have something setup wrong?

---

To Reproduce Steps to reproduce the behavior:

1. I guess just try building a project with code tags? Idk this seems like such a core issue I assume its something on my end.

Expected behavior No exception when reading <code source""> tags

Context (please complete the following information):

• OS: MacOS
• Docfx version: 2.75.2

Extra Context Issue only happens when source is defined. <code><code/> has no issue.

[filzrev]

Is there minimum reproducible sample code?

I'm tested on the following environment. (using GitHub action)

• OS: macOS
• docfx: 2.75.2

But it can't reproduce reported issue. Tested Code: https://github.com/filzrev/docfx.issue9685/tree/main/src/SampleLib

[AlanSherba]

I don't have clear repo steps yet. I beleive the root of the issue is with how my source files are laid out. I am using Unity and am trying to document the contents of a package. The csproj file is in a completely different location than the source files which may be causing an issue?

here's roughly what the directory looks like

> Folder
   > SpatialUnity
        - .csproj
   > Libs
       > unity-package-source
           > runtime
               - *.cs files
       > docfx
           - docfx.json

I have the config setup like so:

{
  "metadata": [
    {
      "src": [
        {
          "src": "../../",
          "files": ["SpatialUnity/SpatialSys.UnitySDK.csproj"]
        }
      ],

This grabs all the correct files, compiles correctly, and outputs nicely. It even outputs the example .cs files. But if I try to use a <code source=""> targeting those examples I get the exception.

[AlanSherba]

exception happens in versions 2.74.1 and greater

[AlanSherba]

I also get the exception when targeting just the CS files with compilation errors disabled:

      "src": [
        {
          "src": "../spatial-unity-sdk/Runtime",
          "files": ["**/*.cs", "*.cs"]
        }
      ],

But in version 2.71.0 this config works perfectly

[AlanSherba]

Defining "codeSourceBasePath": "libs/spatial-unity-sdk-examples", in the docfx.json metadata resolved this on 2.75.2

Umm... but note that the folder syntax for codeSourceBasePath is relative to the root of the gitrepo that the docfx.json is inside. Not relative to docfx.json like everything else. Not relative to the source files or csproj or anything. Seems kinda arbitrary, and maybe a bug?

[filzrev]

It seems that the current implementation resolves codeSourceBasePath using the current directory. It need to fix to use EnvironmentContext.CurrentDirectory instead.

https://github.com/dotnet/docfx/blob/e4d06da4d68ca9d49ad9488a1a124974a885d1e1/src/Docfx.Dotnet/ManagedReference/Visitors/SymbolVisitorAdapter.cs#L722-L725 https://github.com/dotnet/docfx/blob/e4d06da4d68ca9d49ad9488a1a124974a885d1e1/src/Docfx.Dotnet/DotnetApiCatalog.ApiPage.cs#L752-L755