Bug 14452 - Mono.Android.xml documentation file is unusable because of wrong format
Summary: Mono.Android.xml documentation file is unusable because of wrong format
Status: RESOLVED FIXED
Alias: None
Product: Android
Classification: Xamarin
Component: Tools and Addins ()
Version: 4.0
Hardware: PC Windows
: --- normal
Target Milestone: ---
Assignee: Jonathan Pryor
URL:
Depends on:
Blocks:
 
Reported: 2013-09-05 07:35 UTC by Andrew
Modified: 2013-09-10 06:04 UTC (History)
3 users (show)

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


Attachments
missing intellisense documentation in Xamarin Studio (13.63 KB, image/png)
2013-09-05 07:36 UTC, Andrew
Details


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 Andrew 2013-09-05 07:35:38 UTC
The problem is the documentation files shipped with Xamarin.Android are generated in a wrong way, making them unusable.

Consider the following example: "c:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\MonoAndroid\v4.0.3\Mono.Android.xml" 

"name" attribute of "member" node is filled with fully qualified member name, missing "M:", "T:" etc prefix, as well as member parameters (if it's a ctor or a method).

Here's an example of a wrong member:
[code]
<member name="Android.Widget.ImageView.SetMaxWidth">
            <param name="maxWidth">maximum width for this view</param>
            <summary>
 Note that this view could be still smaller than 100 x 100 using this approach if the original
 image is small.</summary>
            <remarks>
                <para>An optional argument to supply a maximum width for this view. Only valid if
 <c><see cref="M:Android.Widget.ImageView.SetAdjustViewBounds(System.Boolean)" /></c> has been set to true. To set an image to be a maximum
 of 100 x 100 while preserving the original aspect ratio, do the following: 1) set
 adjustViewBounds to true 2) set maxWidth and maxHeight to 100 3) set the height and width
 layout params to WRAP_CONTENT.
 
 <para>
 Note that this view could be still smaller than 100 x 100 using this approach if the original
 image is small. To set an image to a fixed size, specify that size in the layout params and
 then use <c><see cref="M:Android.Widget.ImageView.SetScaleType(Android.Widget.ImageView.ScaleType)" /></c> to determine how to fit
 the image within the bounds.
 </para></para>
                <para>
                    <format type="text/html">
                        <a href="http://developer.android.com/reference/android/widget/ImageView.html#setMaxWidth(int)" target="_blank">[Android Documentation]</a>
                    </format>
                </para>
            </remarks>
            <since version="Added in API level 1" />
        </member>
[/code]


Here's I have fixed method documentation by adding "M:" prefix and method parameter type:
[code]
<member name="M:Android.Widget.ImageView.SetMaxHeight(System.Int32)">
            <param name="maxHeight">maximum height for this view</param>
            <summary>
 Note that this view could be still smaller than 100 x 100 using this approach if the original
 image is small.</summary>
            <remarks>
                <para>An optional argument to supply a maximum height for this view. Only valid if
 <c><see cref="M:Android.Widget.ImageView.SetAdjustViewBounds(System.Boolean)" /></c> has been set to true. To set an image to be a
 maximum of 100 x 100 while preserving the original aspect ratio, do the following: 1) set
 adjustViewBounds to true 2) set maxWidth and maxHeight to 100 3) set the height and width
 layout params to WRAP_CONTENT.
 
 <para>
 Note that this view could be still smaller than 100 x 100 using this approach if the original
 image is small. To set an image to a fixed size, specify that size in the layout params and
 then use <c><see cref="M:Android.Widget.ImageView.SetScaleType(Android.Widget.ImageView.ScaleType)" /></c> to determine how to fit
 the image within the bounds.
 </para></para>
                <para>
                    <format type="text/html">
                        <a href="http://developer.android.com/reference/android/widget/ImageView.html#setMaxHeight(int)" target="_blank">[Android Documentation]</a>
                    </format>
                </para>
            </remarks>
            <since version="Added in API level 1" />
        </member>
[/code]

I used Xamarin Studio to take a screenshot (attached) of intellisense for both methods, SetMaxWidth shows no documentation, SetMaxHeight shows all the content properly. The same applies to Visual Studio.

This issue applies to MonoAndroid only (all versions, 1.6-4.2), monotouch.xml works well.
Comment 1 Andrew 2013-09-05 07:36:32 UTC
Created attachment 4782 [details]
missing intellisense documentation in Xamarin Studio
Comment 2 Jonathan Pryor 2013-09-09 14:31:22 UTC
I'm not sure what caused this, but it doesn't appear to happen anymore on master (to be 4.8.3).
Comment 3 Andrew 2013-09-10 06:04:55 UTC
Can you attach the fixed file? My Xamarin.Android is 4.8.1013 and I don't see any way to update it to 4.8.3.