Question: How to generate output for objects that are not documented

hairlesshobo commented 2 years ago

I apologize if this has already been answered. I looked through all the existing issues and was unable to find an answer to this question. The readme has the following note:

Only elements with a xml documentation will appear in the generated documentation.

Is there some setting to override this?

I have several fairly large projects that I intend to use this project for and I've been working to add the missing comments, but doing so takes time. In the meantime, I would still like to see the method declarations and such, even if there is no summary attached to them.

Thanks in advance!

Doraku commented 2 years ago

This was by design at first as there was no way to filter what documentation was supposed to be generated. Since then the <exclude> tag and the <DefaultDocumentationGeneratedAccessModifiers> property have been added to control properly what you want so it may be a good idea to change this behavior and generate everything that respect those configuration now :) I will change it.

hairlesshobo commented 2 years ago

Awesome, thank you!!

Might I suggest you add it as an option? Something like <IncludeUndocumentedElements> to maintain backward compatibility for people who are using your tool and want to maintain the current functionality?

hairlesshobo commented 2 years ago

I know you closed this issue already, so not sure if you want me to create a new issue or post it here, but the new functionality does not appear to work.

When I enabled <DefaultDocumentationIncludeUndocumentedItems>true</DefaultDocumentationIncludeUndocumentedItems> in my .csproj file, this is what happens when I attempt to build:

  2021-09-25 10:53:56.3267|INFO|DefaultDocumentation|Starting DefaultDocumentation with those settings
  2021-09-25 10:53:56.3352|INFO|DefaultDocumentation|LogLevel: 
  2021-09-25 10:53:56.3352|INFO|DefaultDocumentation|AssemblyFile: /home/user/code/libsmb2sharp/LibSMB2Sharp/bin/Debug/netstandard2.0/LibSMB2Sharp.dll
  2021-09-25 10:53:56.3352|INFO|DefaultDocumentation|DocumentationFile: /home/user/code/libsmb2sharp/LibSMB2Sharp/obj/Debug/netstandard2.0/LibSMB2Sharp.xml
  2021-09-25 10:53:56.3352|INFO|DefaultDocumentation|ProjectDirectory: /home/user/code/libsmb2sharp/LibSMB2Sharp/
  2021-09-25 10:53:56.3352|INFO|DefaultDocumentation|OutputDirectory: /home/user/code/libsmb2sharp/docs/api
  2021-09-25 10:53:56.3352|INFO|DefaultDocumentation|AssemblyPageName: 
  2021-09-25 10:53:56.3381|INFO|DefaultDocumentation|InvalidCharReplacement: _
  2021-09-25 10:53:56.3381|INFO|DefaultDocumentation|FileNameMode: FullName
  2021-09-25 10:53:56.3381|INFO|DefaultDocumentation|RemoveFileExtensionFromLinks: False
  2021-09-25 10:53:56.3381|INFO|DefaultDocumentation|NestedTypeVisibilities: Namespace
  2021-09-25 10:53:56.3381|INFO|DefaultDocumentation|GeneratedPages: Namespaces, Types, Members
  2021-09-25 10:53:56.3381|INFO|DefaultDocumentation|GeneratedAccessModifiers: Public, Private, Protected, Internal, ProtectedInternal, PrivateProtected
  2021-09-25 10:53:56.3381|INFO|DefaultDocumentation|IncludeUndocumentedItems: True
  2021-09-25 10:53:56.3381|INFO|DefaultDocumentation|IgnoreLineBreak: True
  2021-09-25 10:53:56.3381|INFO|DefaultDocumentation|LinksOutputFile: 
  2021-09-25 10:53:56.3381|INFO|DefaultDocumentation|LinksBaseUrl: 
  2021-09-25 10:53:56.3405|INFO|DefaultDocumentation|ExternLinksFiles:
/home/user/.nuget/packages/defaultdocumentation/0.7.8/build/DefaultDocumentation.targets(38,5): error MSB4018: The "DefaultDocumentationTask" task failed unexpectedly. [/home/user/code/libsmb2sharp/LibSMB2Sharp/LibSMB2Sharp.csproj]
/home/user/.nuget/packages/defaultdocumentation/0.7.8/build/DefaultDocumentation.targets(38,5): error MSB4018: System.NullReferenceException: Object reference not set to an instance of an object. [/home/user/code/libsmb2sharp/LibSMB2Sharp/LibSMB2Sharp.csproj]
/home/user/.nuget/packages/defaultdocumentation/0.7.8/build/DefaultDocumentation.targets(38,5): error MSB4018:    at DefaultDocumentation.DocItemReader..ctor(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\DocItemReader.cs:line 135 [/home/user/code/libsmb2sharp/LibSMB2Sharp/LibSMB2Sharp.csproj]
/home/user/.nuget/packages/defaultdocumentation/0.7.8/build/DefaultDocumentation.targets(38,5): error MSB4018:    at DefaultDocumentation.DocItemReader.GetItems(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\DocItemReader.cs:line 292 [/home/user/code/libsmb2sharp/LibSMB2Sharp/LibSMB2Sharp.csproj]
/home/user/.nuget/packages/defaultdocumentation/0.7.8/build/DefaultDocumentation.targets(38,5): error MSB4018:    at DefaultDocumentation.Writer.DocItemWriter..ctor(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\Writer\DocItemWriter.cs:line 25 [/home/user/code/libsmb2sharp/LibSMB2Sharp/LibSMB2Sharp.csproj]
/home/user/.nuget/packages/defaultdocumentation/0.7.8/build/DefaultDocumentation.targets(38,5): error MSB4018:    at DefaultDocumentation.Writer.MarkdownWriter..ctor(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\Writer\MarkdownWriter.cs:line 29 [/home/user/code/libsmb2sharp/LibSMB2Sharp/LibSMB2Sharp.csproj]
/home/user/.nuget/packages/defaultdocumentation/0.7.8/build/DefaultDocumentation.targets(38,5): error MSB4018:    at DefaultDocumentation.Generator.Execute(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\Generator.cs:line 19 [/home/user/code/libsmb2sharp/LibSMB2Sharp/LibSMB2Sharp.csproj]
/home/user/.nuget/packages/defaultdocumentation/0.7.8/build/DefaultDocumentation.targets(38,5): error MSB4018:    at DefaultDocumentation.DefaultDocumentationTask.Execute() in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation\DefaultDocumentationTask.cs:line 50 [/home/user/code/libsmb2sharp/LibSMB2Sharp/LibSMB2Sharp.csproj]
/home/user/.nuget/packages/defaultdocumentation/0.7.8/build/DefaultDocumentation.targets(38,5): error MSB4018:    at Microsoft.Build.BackEnd.TaskExecutionHost.Microsoft.Build.BackEnd.ITaskExecutionHost.Execute() [/home/user/code/libsmb2sharp/LibSMB2Sharp/LibSMB2Sharp.csproj]
/home/user/.nuget/packages/defaultdocumentation/0.7.8/build/DefaultDocumentation.targets(38,5): error MSB4018:    at Microsoft.Build.BackEnd.TaskBuilder.ExecuteInstantiatedTask(ITaskExecutionHost taskExecutionHost, TaskLoggingContext taskLoggingContext, TaskHost taskHost, ItemBucket bucket, TaskExecutionMode howToExecuteTask) [/home/user/code/libsmb2sharp/LibSMB2Sharp/LibSMB2Sharp.csproj]

Also, thank you for how quickly you addressed the last two questions I brought to your attention!!

Doraku commented 2 years ago

Gahhh I know exactly what it is, that's what I get for not testing properly sorry >_< I will fix it when I get back. I shouldn't do those things after a bad day at works!

hairlesshobo commented 2 years ago

No problem at all. Believe me, I know how it is!

Out of curiosity, can you point me to a guide somewhere that would show me how to directly include the project and have it run? I tried to debug it myself.. Cloned your repo, added the project reference but the build did not trigger your code to run when it's not included as a nuget module. It's not a big deal, I'm just curious how to debug something like this locally for a future reference.

Doraku commented 2 years ago

Sure, to debug I use DefaultDocumentation.Console, you just have to change the debug application arguments to point to your dll. Most of the code is in DefaultDocumentation.Common so that both projects DefaultDocumentation and DefaultDocumentation.Console just handle the arguments differently. I think it should also be possible to debug the msbuild task by attaching one IDE (with the DefaultDocumentation solution) to an other IDE instance (with your own solution using the DefaultDocumentation package).

Concerning the bug I fixed it but after properly testing it it (this time) an other problem emerged: it now produces documentation for all types and members generated by the compiler :D (backing field, delegate type for lambda) which is a little too much! I will see if there is an attribute somewhere to safely remove all that noise.

Doraku commented 2 years ago

remaining problems:

~class default constructor are still generated, can't find a way to see that they are generated by the compiler >_>~ for now if their is only one constructor with no parameter and no documentation in a class, we see it as generated by the compiler
~enum field value__ generated, but I can add a direct check~ (for reference https://docs.microsoft.com/en-us/dotnet/csharp/misc/cs0076)
I have one weird instance of an interface implementation (not explicit) and for some reason an implicit implementation still ends up in the IL and it's empty documentation is generated, not sure what is going on here

hairlesshobo commented 2 years ago

Awesome, sounds like you are making great progress. I really appreciate you work on this so quickly!

Doraku commented 2 years ago

I'm closing it again :) there is only the weird problem with the generated implicit members but I only see it with one particular method and nowhere else. Maybe if other people observe a similar behavior we can pin point exactly where this comes from. I hope I won't have to open this issue again, I tested it for real this time :D

hairlesshobo commented 2 years ago

Awesome! I've got several projects to give it a whirl on so I'll let you know what I find.

Thanks again!

Doraku / DefaultDocumentation

Question: How to generate output for objects that are not documented #81