Open jmarolf opened 4 years ago
cc: @nguerrera @jasonmalinowski @ryzngard
Another option would be continuing to work on the replacement. 😄
I'd love the editor to collapse down doc comments into something very unintrusive but configurable. Personally I'd want to see as little as the summary inline. Hovering would display the full rendered quick info, and clicking some icon would display the entire comment for editing.
IMO, the format isn't particularly relevant. I have to work with a lot of Java, Scala and Python as well and despite having "simpler" doc comment formats they're still a massive wall of text.
I'd love the editor to collapse down doc comments into something very unintrusive but configurable. Personally I'd want to see as little as the summary inline.
Well, at the very least, in VS, you can already click the [-]
in the margin to collapse doc comments pretty much exactly like that. Also, I would L O V E to have an option to have VS show doc comments collapsed like that as the default.
@sharwell, could you elaborate on "replacement"?
@tannergooding My work in progress is https://gist.github.com/sharwell/ab7a6ccab745c7e0a5b8662104e79735
@sharwell Another option would be continuing to work on the replacement. 😄
Sure, but this could be done in a sprint. rev'ing the whole documentation comment infrastructure is a much bigger proposition
I also see this as an opportunity to enrich markdown comment structures by showing what will be rendered in quick info inline with the comment.
I commented on https://github.com/dotnet/csharplang/issues/2987. I like this idea but think it would also be good to have some kind of language service API or IDE feature that allows a better editing experience as well.
That is, support for rendering documentation comments in a better format would be great and it would also be great if you could edit your documentation comments in a better format (e.g. Markdown, Doxygen, etc) but still have it saved to the recognized XML format on the backend (so the compiler and existing tooling doesn't need to update, etc).
yeah, maybe a better way for me to say it is that we can do both. I don't see a reason for one feature to wait for the other.
One option I thought of: we could have a command that collapses the current comment to just one line (like you normally get when you collapse it from the outlining margin), and opens up a Peek window below it containing the comment text as Markdown instead of XML. When the Peek window is closed, the contents are converted back to XML to place in the documentation comment.
The same strategy could be used for other editing scenarios involving embedded languages, such as string literals with well-defined syntax.
When I click inside the XML doc comments show me the regular XML format. When I am just scrolling through the file, render the comment like it would appear in quickinfo.