Bug 58887 - Automated content that uses <para> tags should be added to Remarks section only
Summary: Automated content that uses <para> tags should be added to Remarks section only
Alias: None
Product: iOS
Classification: Xamarin
Component: Tools ()
Version: XI 10.99 (xcode9)
Hardware: PC Mac OS
: --- enhancement
Target Milestone: Future Cycle (TBD)
Assignee: Bugzilla
Depends on:
Reported: 2017-08-18 18:15 UTC by Mike Norman
Modified: 2017-08-18 20:46 UTC (History)
2 users (show)

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 58887 on Developer Community or GitHub 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: Developer Community HTML or GitHub Markdown
  • 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:

Description Mike Norman 2017-08-18 18:15:00 UTC
The various docfixer tools that add multiparagraph content seem to hit the <param>, <typeparam>, <summary>, <value>, and <returns> sections of the API documentation. As these are the sections that show up in the Intellisense, they are intended to be brief one- or two-sentence descriptions of small pieces of functionality, rather than essays.

Only the <remarks> section should be used for longer content. Either retool to get these tools to change "To be added." to "To be added. (May be null.)", or put lengthier descriptions in the <remarks> section, instead. Obviously, we'd have to start checking for "To be added." at the start of strings, instead of being the entire string, but the existing solution breaks the tooling as it is now by hiding TBA clauses inside a <para> tag.

In the long run, the ECMA schema should disallow <para> tags in <param>, <typeparam>, <summary>, <value>, and (probably) <returns> sections, leaving them only in <remarks> sections.
Comment 1 Sebastien Pouliot 2017-08-18 19:08:50 UTC
I'm not sure if I understand this correctly. E.g. Is this only about generated/initial doc ? or to migrate existing content ?

Can you provide a "bad" (generated) example ? and what should have been generated ?
Comment 2 Mike Norman 2017-08-18 20:29:38 UTC
The writing team (Well, me.) can probably code a solution for migrating existing content.

One existing item that is bad is the following content:
    <para>(More documentation for this node is coming)</para>
    <para tool="nullallowed">This value can be <see langword="null" />.</para>

in MonoTouch.WebKit/WKWebView.xml for the member:

public virtual MonoTouch.Security.SecTrust ServerTrust { get; }

There are several hundred others.

We could probably accept: <value>To be added. Possibly <see langword="null" /></value>

That way, we can still run "begins with" checks, rather than equality checks, for "To be added." to find remaining work.

The authoritative XSD at api-doc-tools/mdoc/Resources/monodoc-ecma.xsd allows para tags, but they're just wrong for the content as we use it. HTH.
Comment 3 Sebastien Pouliot 2017-08-18 20:31:28 UTC
Make sense, thanks!
Comment 4 Mike Norman 2017-08-18 20:46:21 UTC
<value>To be added. Possibly <see langword="null" />.</value>

I left out the final "." in my previous comment. Tough one to spot, and didn't want to be responsible for a copypasta error. :)