Bug 18306 - mdoc does not support documentation of optional parameters
Summary: mdoc does not support documentation of optional parameters
Status: NEW
Alias: None
Product: Tools
Classification: Mono
Component: Doctools ()
Version: unspecified
Hardware: PC Mac OS
: High normal
Target Milestone: ---
Assignee: Joel Martinez
URL:
Depends on:
Blocks:
 
Reported: 2014-03-11 15:54 UTC by Larry O'Brien
Modified: 2014-03-11 23:35 UTC (History)
5 users (show)

Tags:
Is this bug a regression?: ---
Last known good build:

Notice (2018-05-24): bugzilla.xamarin.com is now in read-only mode.

Please join us on Visual Studio Developer Community and in the Xamarin and 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 Links.

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 original description:

  • Export the original title and description: GitHub Markdown or Developer Community HTML
  • Copy the title and description into the new report. Adjust them to be up-to-date if needed.
  • Add your new information.

In special cases on GitHub you might also want the comments: GitHub Markdown with public comments

Related Links:
Status:
NEW

Description Larry O'Brien 2014-03-11 15:54:23 UTC
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">
Comment 1 Miguel de Icaza [MSFT] 2014-03-11 16:58:19 UTC
Update:

The mdoc tool supports this, but the renderer into HTML does not.

So we need to patch the renderer.
Comment 2 Miguel de Icaza [MSFT] 2014-03-11 16:58:31 UTC
We want this for Duplo who relies on this very much.
Comment 3 Jonathan Pryor 2014-03-11 19:17:44 UTC
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...

...maybe.

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:

Monodoc: http://docs.go-mono.com/?link=M%3aSystem.String.Format(string%2cobject%5b%5d)

MSDN: http://msdn.microsoft.com/en-us/library/b1csw23d(v=vs.110).aspx

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.
Comment 4 Jonathan Pryor 2014-03-11 19:19:06 UTC
Note the closing ')' in the Monodoc link; without it, it doesn't resolve. (Damn auto-hyperlinkers!)
Comment 5 Miguel de Icaza [MSFT] 2014-03-11 22:09:03 UTC
Jonathan,

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.
Comment 6 Jonathan Pryor 2014-03-11 23:35:24 UTC
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.