Giters

Doraku / DefaultDocumentation

Create a simple markdown documentation from the Visual Studio xml one.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

System.Exception when building do to file name length

Ecotone123 opened this issue · comments

commented

I'm getting this error when building:

Error MSB4018 The "DefaultDocumentationTask" task failed unexpectedly. System.Exception: Error while writing documentation for TBMCS.Server.Services.FluentValidationExtensions.FriendlyUnitIdExistAsync<T>(this FluentValidation.IRuleBuilder<T,string>, System.Linq.Expressions.Expression<System.Func<T,string>>, TBMCS.Server.Persistence.McampContext) ---> System.IO.DirectoryNotFoundException: Could not find a part of the path 'C:\Projects\TBMCS\Working Branches\3274 - USMTFWriterQueue documentation\docs\TBMCS.Server.Services.FluentValidationExtensions.FriendlyUnitIdExistAsync_T_(thisFluentValidation.IRuleBuilder_T,string_,System.Linq.Expressions.Expression_System.Func_T,string__,TBMCS.Server.Persistence.McampContext).md'.

It's caused by the file name length (plus path). Using the Members option can result in very long file names. Maybe leave out the parameter list and just have maybe a number for overloads.

commented

I found that I can use configuration setting to resolve this issue although I think the default filename factory should be updated to shorten file names.

commented

What configuration did you use to avoid this error?

commented

As stated in the readme:

FileNameFactory

  • csproj property: <DefaultDocumentationFileNameFactory>...</DefaultDocumentationFileNameFactory>
  • tool argument: --FileNameFactory ...
  • configuration file: "FileNameFactory": "..."

Name or Type Assembly of the IFileNameFactory implementation to use to generate the name of pages. Available implementations are:

  • FullName or DefaultDocumentation.Markdown.FileNameFactories.FullNameFactory DefaultDocumentation.Markdown uses the fully qualified name of each member
  • Name or DefaultDocumentation.Markdown.FileNameFactories.NameFactory DefaultDocumentation.Markdown removes the namespace (collisions can happen if there is multiple types with the same name in different namespaces)
  • Md5 or DefaultDocumentation.Markdown.FileNameFactories.Md5Factory DefaultDocumentation.Markdown uses a Md5 of the full name of each member to produce shorter name, collisions can happen
  • NameAndMd5Mix or DefaultDocumentation.Markdown.FileNameFactories.NameAndMd5MixFactory DefaultDocumentation.Markdown removes the namespace and use a Md5 for parameters
    The default value is FullName. All those implementations WILL delete any .md file EXCEPT a file named readme.md.

FullName is the default as it is the one with no risk of collusion, but it has the risk of producing a path too long, there's no perfect value saddly.