api-doc-tools icon indicating copy to clipboard operation
api-doc-tools copied to clipboard

EditorBrowsable state arguments ommitted in at least one case

Open MichaelNorman opened this issue 7 years ago • 1 comments

mdoc update was run on a DLL that resulted from, among other code:

[EditorBrowsable(EditorBrowsableState.Never)]
		public void SetAndLoadSource(Uri value, string resourcePath, Assembly assembly, System.Xml.IXmlLineInfo lineInfo)
		{
			_source = value;
			if (_mergedWith != null)
				throw new ArgumentException("Source can not be used with MergedWith");

			//this will return a type if the RD as an x:Class element, and codebehind
			var type = XamlResourceIdAttribute.GetTypeForPath(assembly, resourcePath);
			if (type != null)
				_mergedInstance = s_instances.GetValue(type, (key) => (ResourceDictionary)Activator.CreateInstance(key));
			else
				_mergedInstance = DependencyService.Get<IResourcesLoader>().CreateFromResource<ResourceDictionary>(resourcePath, assembly, lineInfo);
			OnValuesChanged(_mergedInstance.ToArray());
		}

In the resulting XML, the (EditorBrowsableState.Never) was omitted:

<Member MemberName="SetAndLoadSource">
      <MemberSignature Language="C#" Value="public void SetAndLoadSource (Uri value, string resourcePath, System.Reflection.Assembly assembly, System.Xml.IXmlLineInfo lineInfo);" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig instance void SetAndLoadSource(class System.Uri value, string resourcePath, class System.Reflection.Assembly assembly, class System.Xml.IXmlLineInfo lineInfo) cil managed" />
      <MemberSignature Language="DocId" Value="M:Xamarin.Forms.ResourceDictionary.SetAndLoadSource(System.Uri,System.String,System.Reflection.Assembly,System.Xml.IXmlLineInfo)" />
      <MemberSignature Language="F#" Value="member this.SetAndLoadSource : Uri * string * System.Reflection.Assembly * System.Xml.IXmlLineInfo -&gt; unit" Usage="resourceDictionary.SetAndLoadSource (value, resourcePath, assembly, lineInfo)" />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyName>Xamarin.Forms.Core</AssemblyName>
        <AssemblyVersion>2.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <Attributes>
        <Attribute>
          <AttributeName>System.ComponentModel.EditorBrowsable</AttributeName>
        </Attribute>
      </Attributes>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="value" Type="System.Uri" />
        <Parameter Name="resourcePath" Type="System.String" />
        <Parameter Name="assembly" Type="System.Reflection.Assembly" />
        <Parameter Name="lineInfo" Type="System.Xml.IXmlLineInfo" />
      </Parameters>
      <Docs>
        <param name="value">To be added.</param>
        <param name="resourcePath">To be added.</param>
        <param name="assembly">To be added.</param>
        <param name="lineInfo">To be added.</param>
        <summary>For internal use by the Xamarin.Forms platform.</summary>
        <remarks>To be added.</remarks>
      </Docs>
    </Member>

Expected: The EditorBrowsableState.Never attribute value is present in the Attribute markup.

Impact: Users will see, in Intellisense, APIs for infrastructure that are not useful for them, cluttering their experience. Another, minor, impact is that some of the DocStat tooling depends on these attributes being named explicitly. Their existing format has been relied upon.

MichaelNorman avatar Apr 23 '18 19:04 MichaelNorman

Awesome, thanks for the bug report @MichaelNorman. One note though:

Impact: Users will see, in Intellisense, APIs for infrastructure that are not useful for them, cluttering their experience.

VS/VSMac doesn’t use the value from the XML to determine whether to show or not, it’s embedded in the assembly metadata … so the user is not affected at all in the IDE.

joelmartinez avatar Apr 23 '18 19:04 joelmartinez