Bug 59423 - Please globally remove code from doc tools that uses `Element.Value`
Summary: Please globally remove code from doc tools that uses `Element.Value`
Status: RESOLVED FIXED
Alias: None
Product: iOS
Classification: Xamarin
Component: Documentation ()
Version: XI 10.99 (xcode9)
Hardware: PC Mac OS
: --- normal
Target Milestone: Future Cycle (TBD)
Assignee: Manuel de la Peña [MSFT]
URL:
Depends on:
Blocks:
 
Reported: 2017-09-12 14:54 UTC by Mike Norman
Modified: 2017-09-21 08:47 UTC (History)
3 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 on Developer Community or GitHub with your current version information, steps to reproduce, and relevant error messages or log files if you are hitting an issue that looks similar to this resolved bug and you do not yet see a matching new report.

Related Links:
Status:
RESOLVED FIXED

Description Mike Norman 2017-09-12 14:54:32 UTC
There's another similar bug for summaries, but this occurred in a parameter:
"<param name="presetName">The preset name (,
,
,
,
,
,
 or 
).</param>"

This parameter value (in MonoTouch.AVFoundation.AVAssetExportSession.DetermineCompatibilityOfExportPresetAsync) was copied, more than likely with SomeElement.Value = SomeOtherElement.Value. This only works if Value has no tags in it, and is therefore incorrect in any XML element that allows child elements. Please fix this globally:
1) With a global search.
2) Now.
3) Before doing any more work on the toolchain that copies content from one topic to another.

Also, find all the places where this code as broken the ios-api-docs xml and fix them, please.

It's just not acceptable the way it is.
Comment 1 Alex Soto [MSFT] 2017-09-13 00:44:47 UTC
I can confirm this inside ios-api-docs/en/MonoTouch.AVFoundation/AVAssetExportSession.xml just like Mike pointed out.
Comment 2 Sebastien Pouliot 2017-09-19 21:10:55 UTC
similar to #58447
Comment 3 Manuel de la Peña [MSFT] 2017-09-20 10:29:10 UTC
Looking at docfixer and doing a grep we have the following:

https://gist.github.com/mandel-macaque/45d4bee7a403415328701febcd886952

AFAIK there are two occurrences we have to take care which are the ones for summaries and parameters, that have to be modified. PR https://github.com/xamarin/maccore/pull/564

Does deal with both of them.

After the merge of the PR the docs will look like:

      <Docs>
        <param name="asset">To be added.</param>
        <param name="presetName">The preset name (<see cref="P:MonoTouch.AVFoundation.AVAssetExportSession.PresetLowQuality" />,
<see cref="P:MonoTouch.AVFoundation.AVAssetExportSession.PresetMediumQuality" />,
<see cref="P:MonoTouch.AVFoundation.AVAssetExportSession.PresetHighestQuality" />,
<see cref="P:MonoTouch.AVFoundation.AVAssetExportSession.Preset640x480" />,
<see cref="P:MonoTouch.AVFoundation.AVAssetExportSession.Preset960x540" />,
<see cref="P:MonoTouch.AVFoundation.AVAssetExportSession.Preset1280x720" />,
<see cref="P:MonoTouch.AVFoundation.AVAssetExportSession.PresetAppleM4A" /> or
<see cref="P:MonoTouch.AVFoundation.AVAssetExportSession.PresetPassthrough" />).</param>
        <summary>Creates an export session from an AVAsset and a preset name.</summary>
        <remarks>To be added.</remarks>
      </Docs>

Which ensures that mix-mode xml works. The summary is also fixed in a similar way.
Comment 4 Manuel de la Peña [MSFT] 2017-09-21 08:47:04 UTC
Closing bug since PR landed. This will later be added via a bump-pr in xamarin-ios.