search

Doraku / DefaultDocumentation

Create a simple markdown documentation from the Visual Studio xml one.
MIT No Attribution
157 stars 26 forks source link

DefaultDocumentation crashes #76

Closed jonasrembratttetrapak closed 2 years ago

jonasrembratttetrapak commented 3 years ago

Hi, and thanks for helping me resolve the crash some weeks ago. Unfortunately I now have another, with this result:

 DefaultDocumentation.targets(38, 5): [MSB4018] The "DefaultDocumentationTask" task failed unexpectedly.
System.Xml.XmlException: '<', hexadecimal value 0x3C, is an invalid attribute character. Line 2042, position 59.
   at System.Xml.XmlTextReaderImpl.Throw(Exception e)
   at System.Xml.XmlTextReaderImpl.Throw(String res, String[] args)
   at System.Xml.XmlTextReaderImpl.ParseAttributeValueSlow(Int32 curPos, Char quoteChar, NodeData attr)
   at System.Xml.XmlTextReaderImpl.ParseAttributes()
   at System.Xml.XmlTextReaderImpl.ParseElement()
   at System.Xml.XmlTextReaderImpl.ParseElementContent()
   at System.Xml.XmlTextReaderImpl.Read()
   at System.Xml.XmlTextReader.Read()
   at ICSharpCode.Decompiler.Documentation.XmlDocumentationProvider.ReadMembersSection(XmlTextReader reader, LinePositionMapper linePosMapper, List`1 indexList)
   at ICSharpCode.Decompiler.Documentation.XmlDocumentationProvider.ReadXmlDoc(XmlTextReader reader)
   at ICSharpCode.Decompiler.Documentation.XmlDocumentationProvider..ctor(String fileName)
   at DefaultDocumentation.DocItemReader..ctor(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\DocItemReader.cs:line 40
   at DefaultDocumentation.DocItemReader.GetItems(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\DocItemReader.cs:line 214
   at DefaultDocumentation.Writer.DocItemWriter..ctor(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\Writer\DocItemWriter.cs:line 25
   at DefaultDocumentation.Writer.MarkdownWriter..ctor(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\Writer\MarkdownWriter.cs:line 27
   at DefaultDocumentation.Generator.Execute(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\Generator.cs:line 7
   at DefaultDocumentation.DefaultDocumentationTask.Execute() in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation\DefaultDocumentationTask.cs:line 44
   at Microsoft.Build.BackEnd.TaskExecutionHost.Microsoft.Build.BackEnd.ITaskExecutionHost.Execute()
   at Microsoft.Build.BackEnd.TaskBuilder.ExecuteInstantiatedTask(ITaskExecutionHost taskExecutionHost, TaskLoggingContext taskLoggingContext, TaskHost taskHost, ItemBucket bucket, TaskExecutionMode howToExecuteTask)

Like before, I suspect I might have done a boo-boo somewhere in the code documentation but there is no convenient way to isolate the culprit unless you dump the actual error to the console (or a file). I checked the .xml file but the line mentioned (2042) doesn't exist so I guess it's referring to some other source?

The project running DefaultDocumentation in this case is here: https://github.com/Tetra-Pak-APIs/TetraPak.AspNet/tree/master/TetraPak.AspNet.Api

Doraku commented 3 years ago

Hum when I try to debug it it doesn't fail, but I know I have fixed some stuff between the 0.7.6 and the 0.7.7 version I just created. With the latest version you will also be able to set the logs level (check <DefaultDocumentationLogLevel> in the readme) so it will be a lot easier to see where something goes wrong now.

jonasrembratttetrapak commented 3 years ago

Thanks! I'll upgrade and try out the new logging features!

jonasrembratttetrapak commented 2 years ago

Hum when I try to debug it it doesn't fail, but I know I have fixed some stuff between the 0.7.6 and the 0.7.7 version I just created. With the latest version you will also be able to set the logs level (check <DefaultDocumentationLogLevel> in the readme) so it will be a lot easier to see where something goes wrong now.

I upgraded and tested again but the error persists. Also, where should I find the detailed log output? The Console only presents the stack trace: 

C:\Users\(me)\.nuget\packages\defaultdocumentation\0.7.7\build\DefaultDocumentation.targets(38,5): Error MSB4018 : The "DefaultDocumentationTask" task failed unexpectedly.
System.Xml.XmlException: '<', hexadecimal value 0x3C, is an invalid attribute character. Line 2042, position 59.
   at System.Xml.XmlTextReaderImpl.Throw(Exception e)
   at System.Xml.XmlTextReaderImpl.Throw(String res, String[] args)
   at System.Xml.XmlTextReaderImpl.ParseAttributeValueSlow(Int32 curPos, Char quoteChar, NodeData attr)
   at System.Xml.XmlTextReaderImpl.ParseAttributes()
   at System.Xml.XmlTextReaderImpl.ParseElement()
   at System.Xml.XmlTextReaderImpl.ParseElementContent()
   at ICSharpCode.Decompiler.Documentation.XmlDocumentationProvider.ReadMembersSection(XmlTextReader reader, LinePositionMapper linePosMapper, List`1 indexList)
   at ICSharpCode.Decompiler.Documentation.XmlDocumentationProvider.ReadXmlDoc(XmlTextReader reader)
   at ICSharpCode.Decompiler.Documentation.XmlDocumentationProvider..ctor(String fileName)
   at ICSharpCode.Decompiler.Documentation.XmlDocLoader.LoadDocumentation(PEFile module)
   at DefaultDocumentation.DocItemReader.TryGetDocumentation(IEntity entity, XElement& documentation) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\DocItemReader.cs:line 229
   at DefaultDocumentation.DocItemReader.<>c__DisplayClass7_1.<TryGetDocumentation>b__3(IMember e) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\DocItemReader.cs:line 258
   at System.Linq.Enumerable.TryGetFirst[TSource](IEnumerable`1 source, Func`2 predicate, Boolean& found)
   at System.Linq.Enumerable.FirstOrDefault[TSource](IEnumerable`1 source, Func`2 predicate)
   at DefaultDocumentation.DocItemReader.TryGetDocumentation(IEntity entity, XElement& documentation) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\DocItemReader.cs:line 254
   at DefaultDocumentation.DocItemReader..ctor(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\DocItemReader.cs:line 129
   at DefaultDocumentation.DocItemReader.GetItems(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\DocItemReader.cs:line 292
   at DefaultDocumentation.Writer.DocItemWriter..ctor(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\Writer\DocItemWriter.cs:line 25
   at DefaultDocumentation.Writer.MarkdownWriter..ctor(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\Writer\MarkdownWriter.cs:line 29
   at DefaultDocumentation.Generator.Execute(Settings settings) in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation.Common\Generator.cs:line 19
   at DefaultDocumentation.DefaultDocumentationTask.Execute() in D:\a\DefaultDocumentation\DefaultDocumentation\source\DefaultDocumentation\DefaultDocumentationTask.cs:line 48
   at Microsoft.Build.BackEnd.TaskExecutionHost.Microsoft.Build.BackEnd.ITaskExecutionHost.Execute()
   at Microsoft.Build.BackEnd.TaskBuilder.ExecuteInstantiatedTask(ITaskExecutionHost taskExecutionHost, TaskLoggingContext taskLoggingContext, TaskHost taskHost, ItemBucket bucket, TaskExecutionMode howToExecuteTask)
jonasrembratttetrapak commented 2 years ago

@Doraku Could you check the "doc/api" branch of the project (https://github.com/Tetra-Pak-APIs/TetraPak.AspNet/tree/master/TetraPak.AspNet.Api) and see it you get the same problem?

Doraku commented 2 years ago

ok I am not entirely sure here are some observation:

My guess: if you use a local nuget source to automatically refer the TetraPak.AspNet package, at one point you produced an invalid documentation for this project but a package was created and put in the nuget cache %userprofile%\.nuget\packages\tetrapak.aspnet. Even if you update the documentation of this project and replace it in your local nuget source, the old version in the nuget cache will still be used and you get the error. By replacing the PackageReference with a ProjectReference I don't get any error. I hope this help :/

jonasrembratttetrapak commented 2 years ago

Many good points there and I'll look into it.

About the TetraPak.AspNet project: Yes, I wanted to try out your latest version of DefaultCosumentation with one package before I added it to another. Silly decision, really, as I could've just reverted if needed. :-)

Yes, I'm using local Nuget packages for now (I don't want to upload unfinished pckages to nuget.org) but I should have uploaded the "project referencing" version to the branch, to make it build for you. Sorry about that. If I can't figure out what's going on I'll make sure to upload a new commit, with project references instead.

Thanks!

Doraku commented 2 years ago

If you delete the nuget local cache it should take the updated version from your local nuget sources maybe just doing so will make the error go away :) oh and by the way the logs should be in the Output window (output from Build). An other thing, since your TetraPak.AspNet.Api project probably reference some items of the TetraPak.AspNet project in its documentation, you should look into https://github.com/Doraku/DefaultDocumentation#extern-links. Basically set <DefaultDocumentationLinksOutputFile> and <DefaultDocumentationLinksBaseUrl> on the TetraPak.AspNet project for it to generate links to its documentation and feed this file in <DefaultDocumentationExternLinksFiles> on the TetraPak.AspNet.Api project. Otherwise DefaultDocumentation will try to generate dotnet api links for your own types because it doesn't know where their documentation is. I hope to make this process a little more automatique for project referencing one an other but you have to set it up manually for now.

jonasrembratttetrapak commented 2 years ago

I think you where right about the Nuget-versioning being incorrect. When I followed your advice and built the ...Api project using project references instead of package references it works fine.

And I gotta say I had not understood MSBuild "sees" and fixes Nuget references when I use project referencing. I need to experiment a bit with that but if that is true you will have saved me a ton of time bro! I just hope I can return the favor somehow. :-D

Doraku commented 2 years ago

Just spreading the good word :) while it has some caveat the whole msbuild and project ssdk was made by people much smarter than me!

Doraku commented 2 years ago

If that's ok with you I will close this issue now, don't hesitate to reopen it if you feel there is an other problem that we missed :)