Notice (2018-05-24): bugzilla.xamarin.com is now in
Please join us on
Visual Studio Developer Community and in the
Mono organizations on
GitHub to continue tracking issues. Bugzilla will remain
available for reference in read-only mode. We will continue to work
on open Bugzilla bugs, copy them to the new locations
as needed for follow-up, and add the new items under Related
Our sincere thanks to everyone who has contributed on this bug
tracker over the years. Thanks also for your understanding as we
make these adjustments and improvements for the future.
Please create a new report for Bug 18306 on
GitHub or Developer Community if you have new
information to add and do not yet see a matching new report.
If the latest results still closely match this report, you can use the
In special cases on GitHub you might also want the comments:
GitHub Markdown with public comments
MDoc does not currently support documentation of optional parameters. It should.
APIs appear more complex than necessary if optional parameters are not documented. More APIs are using optional parameters, so this is likely to be a bigger problem in the future.
User value: Understanding APIs will be easier if it clearly documented which args have default values. (Is it important to say "The default value of foo is 42"? Or is it sufficient /better to say "Foo is an optional argument"?)
Technical : Default values are in the `MemberSignature` element, but are not trivial to parse out. JonP suggests removing the use of XSLT to generate C# declarations but warns that this would remove functionality (cannot click on types-within-signatures) and have broad impact (require much unit-testing).
Workaround: Optional arguments should be documented in the `param` element, similar to how we document nullallowed: <para tool="nullallowed">
The mdoc tool supports this, but the renderer into HTML does not.
So we need to patch the renderer.
We want this for Duplo who relies on this very much.
Aside: I've been wanting to remove the XSLT-based C# "generator" within monodoc.dll for _years_, because:
1. it's a huge bit of complexity in the XSLT, and removing it would simplify things, and
2. It's "duplicative": mdoc needs this _anyway_ (it's part of the ECMA format), so why does monodoc have an entirely separate copy?
Add in that monodoc.dll is now "old" (mdoc supports both C#4 dynamic and C#4 default parameter values; monodoc supports neither), and we might have a reason to clean this up...
The reason for the XSLT-based C# "generator" is that it can make different parts of the C# signature hyperlinks, because it "knows" what's a link. Compare:
At a glance, they _look_ the same.
However, if you hold your mouse over the keywords _within the signature_, e.g. the return type, in monodoc the Signature's return type is a hyperlink. In MSDN it is _not_. (This is also why MSDN now has "Type:" sections for parameters and the Return Value, which monodoc doesn't currently generate.)
IMHO, monodoc.dll output is _nicer_. However, it's less "scalable" (how do we sanely support other languages? we don't!) and increases maintenance burden.
We should follow MSDN output.
Note the closing ')' in the Monodoc link; without it, it doesn't resolve. (Damn auto-hyperlinkers!)
Good feedback, long term the idea is to replace the XSLT formatter with a Razor/C# one, and I think that is a good goal, but not for the short term (this is already on Joel's to-do list).
There have been several attempts at replacing MonoDoc.dll and the XSLT engine, each attempt has failed short because it was a rewrite (http://www.jwz.org/doc/cadt.html).
This is why we are taking a more evolutionary approach this time around, and we will take on Razor when we are ready to dedicate the time to ensure that every single feature makes it across the conversion, and not just the most expedient ones.
As for adding more languages, we are in no rush to do that at this point.
This isn't about replacing _all_ the XSLT.
This is about removing the C# "generating" parts of the XSLT, e.g. the "getmodifiers" template (and maketypelink, makenamespacelink, CreateSignature, ...), which is all manner of hairiness, replacing them with an XSLT fragment which just emits the //MemberSignature/@Value value.
This would be significantly easier than replacing the XSLT-based engine -- most of it would be preserved. It would be entirely evolutionary.
If you want C#4 features in the HTML output, I really see only two ways to do it:
1. Add _more_ hairy XSLT code which will (by necessity!) need to parse the //MemberSignature/@Value value to deduce default parameter values, etc., and insert this into the generated HTML.
2. Do as I suggest: _simplify_ the XSLT code, and "just" have it emit //MemberSignature/@Value. mdoc would thus be the sole source of member declarations, as provided in the ECMA XML.