Project-system: Support `GenerateDocumentationFile` as checkbox/boolean

[brthor]

See details on default for DocumentationFile here:
https://github.com/dotnet/sdk/issues/67

Filing this to track any project system changes that would need to happen.

cc @davkean

[srivatsn]

I think this I just a targets change and that. There's no project system change needed

[davkean]

There is, it's switched from a path to a bool.

[jnm2]

I was going to file an issue asking if there was a better way to specify the filename than bin\Debug\netstandard1.3\ProjectName.xml, what with multiple configurations and multiple targets. But I'd be just as happy with a bool because I can't think of a scenario in which I'd want to customize the name.

[AArnott]

The text field currently in the project designer is faulty. I was about to file an issue but if you're going to change it to a checkbox anyway, that's fine.

See https://github.com/dotnet/sdk/issues/703 for a couple related issues.

[nguerrera]

This needs to be in ASAP to get checkbox localized.

[nguerrera]

Diregard loc comment, there is already a checkbox in the dialog, we just need to make the behavior smarter based on the capability:

If the user checks the box but does not change the default, then only #true` should be written.

[dsplaisted]

If the user checks the box but does not change the default, then only true should be written.

Is there value in allowing the user to edit this value? If you really want to change it, it's probably going to be hard to get the path right using the dialog. We could say that if you do need to change the path you can do so via editing the project file.

[nguerrera]

That`s fine, then we need to hide the text box and show only the checkbox. Either way, no loc impact. :)

[tmeschter]

@brthor It looks like the change for https://github.com/dotnet/sdk/issues/67 was reverted. Was support for a default DocumentationFile ever added back?

[davkean]

Yes, GenerateDocumentationFile should generate it.

[tmeschter]

The fix for this will include the following:

1. Eliminating the text box entirely.
2. Updating the check box to toggle the GenerateDocumentationFile property.
3. Change the check box label from "XML documentation file:" to "Generate XML documentation file".

[nguerrera]

Note there's a bug in VB handling of GenerateDocumentationFile: https://github.com/dotnet/sdk/issues/1598

We should make sure to fix this in the same release that we do the steps above.

[tmeschter]

In that case I'm going to mark this as blocked until https://github.com/dotnet/sdk/issues/1598 is fixed.

[tmeschter]

Other sticking point: the Build properties window isn't used just by CPS-based projects. So we either need to make a modification that works for all consuming project types, or we needs some way to customize this, or we just split it off entirely for CPS-based projects.

[tmeschter]

Doesn't meet the bar for 15.5 any more. Moving to 15.6.

[dasMulli]

Any chance to bump the prio on this?

I've helped a few devs troubleshoot documentation publishing (use case was almost always swagger API doc) and the root cause seemed to be faulty DocumentationFile paths or the path set for only the debug configuration.

As long as https://github.com/dotnet/sdk/pull/1848 goes into the SDK to fix the VB issue, there shouldn't be any issue blocking this.

[Pilchie]

The team is unlikely to get to this in the 15.6 timeframe, as we're focused on performance and issues that are totally blocking. We'd love PRs though.

[nguerrera]

Removed Blocked label because linked SDK bug is fixed.

[nguerrera]

Changed the title to represent the request more directly. Can we retriage this for dev16? This comes up a lot and every time I tell someone to use GenerateDocumentationFile=true to fix their issues, I have to say that there's an issue with the property pages.

[Pilchie]

Tagging @cartermp - we're hoping to take a larger look at the property pages all up. It's currently behind performance, compat, and .NET Core 3.0 work, so it might not make 16.0, but we'd like to address it in a 16.x at least.

[cartermp]

Do we have an idea of how much work it is to change this area in isolation?

[Pilchie]

Generally, changing the property pages to respect new options requires threading a bunch of stuff though a PIA. The last time @tmeschter touched it was about 2-weeks. Not sure if this would be more or less than that case, and we might be able to amortize it with other work (like support for Warning Waves options if C# decides to proceed with that).

[cartermp]

Yep, makes sense.

[tmeschter]

I mentioned this before, but I'll mention it again: whatever changes we make to the UI here must support both SDK and non-SDK projects. Realistically, I think what we'd do is preserve the current checkbox and field for non-SDK projects and create an entirely new checkbox for SDK projects, and dynamically show one or the other depending on what kind of project it is.

If we don't need to support a new project property in the csproj project system then we can probably skip all the COM stuff we would otherwise need to do and the cost comes down to something like three days.

[martinspasovski]

I found a 'fix' way.
If you set the OutputPath to: bin\Debug\netcoreapp2.2\win-x64\wwwroot\ as example.
You will get the documentation in the above OutputPath folder.

[tmeschter]

@jjmew I would like to see this moved off the backlog and scheduled. For CPS-based projects the project properties UI related to generating doc comment files is effectively broken. At this point we've built out enough expertise with modifying that UI that it shouldn't be as expensive as it would have been in the past.

[jjmew]

@tmeschter I moved it to 16.4

[JVimes]

The current checkbox usually breaks the build (edit: or produces wrong results) on other machines. Is there a reason this is taking years to fix? 🙁

[jjmew]

@JVimes unfortunately we have limited resources and we have been working on higher priority items. We welcome any help 😊

[JVimes]

@jjmew Are you sure that prioritization practices don't cause starvation for issues like this? If so, okeey.

[jjmew]

The process is not perfect but main challenge is not the process but the number of open issues that we have. Currently we have 611 issues. We welcome any help that we can get 😀

[jnm2]

@jjmew Is there any way a community member could help with an issue like this, for example me? If so, guidance docs and a help wanted tag are a standard way of making this possible.

[drewnoakes]

@jnm2 we do have a help wanted label for this project. We've had relatively low community engagement on this repo and are keen to hear how you think we can better facilitate people who would like to contribute.

The project system has a pretty steep learning curve and is a largely unknown, behind-the-scenes component for most users. I've assumed these are reasons why we've seen low engagement.

We 100% welcome anyone who feels passionately enough about any issue (whether 'help wanted' or not) to dig in and make an improvement. It's always best to discuss what you're wanting to do with the team, as this can save time and help avoid frustration or disappointment.

The docs/repo folder has documentation intended for developers of this repo itself, and the getting started doc there is a good place to start.

More information is available in CONTRIBUTING.md.

That said, the docs are not perfect, so open issues with any questions and we'll look to improve the docs and help contributors be productive.

[2mik]

In my opinion, the problem is that so small issue like this one requires so long term process to fix it up. Many people already have spent a lot of time to create several related tickets, discuss them, change many labels and statuses. As a result much more time have been spent than needed to resolve the issue doing real work. And nothing done yet. It's just a checkbox that works for .NET 4.x. No "help wanted", "real work wanted" label is needed.

[dasMulli]

On the "just a checkbox" thing: it's a bit more complicated considering the code has to deal with sdk and non-sdk projects and deal with different combinations of all the properties being set.
I had a look at the code a year ago and figured I don't have enough knowledge of the project system architecture and what types of projects are out there to work on this given that i'm okay with editing csprojs (/ Directory.Build.props). (plus VB also put me off)
Source code for this is - if i'm not mistaken - around https://github.com/dotnet/project-system/blob/master/src/Microsoft.VisualStudio.Editors/PropPages/BuildPropPage.vb#L468

[2mik]

Thanks for the clarification

[JVimes]

Adding a checkbox that assures an XML tag should _never_ be this hard. Has anyone yet discussed writing a new project editor, tailored just for SDK-style projects? I'm not sure SDK-style users have the same desires or needs as legacy project users.

[davkean]

@JVimes Yes, we've thought about this and investigating it for the future for the exact reason why it costs so much to add this check box.

[2mik]

If enter in the existing text field the following bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml, it works as needed. The simplest solution is setting this value by default. New project editor may not appear soon.

[grimreaper38uk]

Entering bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml in the field works the first time, but then going back to the property page shows the decoded (and now hardcoded) path.
Until this is fixed, my team no longer have accurate XML documentation when using project libraries.

[drewnoakes]

We are working on a redesign of the property pages at the moment, which will include a fix for this issue.

[pdevito3]

One more voice of support for a non-absolute path for the xml documentation.