api-doc-tools
api-doc-tools copied to clipboard
mono
Members with private parameters should not be included in ECMAXML
if a member takes a parameter that is of private type, this member cannot be invoked by user, so it should not be in ECMAXML.
@joelmartinez do we have any sort of differentiation between the parameter types that are being fetched inside members? I am guessing that is not the case because mdoc does pure reflection, but I wonder if we need to account for the scenario @TianqiZhang is describing here.
No I think it just includes whatever is there ... but, is it even possible to have a public class/member, with a private parameter? wouldn't the compiler complain about that?
After a bit of investigation, it seems that the MakeMember needs to be investigated ... this is where the code decides whether a member's visibility is appropriate for documentation (by way of the signature formatters). It should probably explicitly look at the reflected member info.
Additionally, the DoUpdateType2 method should probably be updated to check the member's visibility ... one would assume that once a member is shipped, its visibility would not change, but we can never assume too much ;)
Ok, so I've written some unit tests, against this check to ensure we don't document private members. Unfortunately, this code seems to be behavior as expected. The private constructor (that accepts a private class) returns a null signature, which means mdoc would not create an XML stub.
As I commented previously ... the compiler won't even let you create a member that accepts an argument with lesser visibility. So I'm wondering if this is perhaps just some edge case where the member's visibility changed from one version to the next?
@dend & @TianqiZhang ... are we processing multiple versions of the library in question, any chance you could look and see if this member's visibility changed from one version to the next? If so, we would need to decide how to handle this scenario
@TianqiZhang @mairaw @BillWagner - does this have anything to do with the content that we imported into ECMAXML instead of re-generating it? Given that mdoc is not likely the source of the problem.
@dend @joelmartinez sorry that I missed this conversation. No the visibility of this member never changed, it's always been a public constructor with a private parameter. The reason it can exist is probably because it's un-managed.
The type name is System.Diagnostics.SymbolStore.SymDocument, dll name is ISymWrapper.dll. It exists through .Net 4.5 to 4.7. The constructor looks like this:
public unsafe SymDocument(ISymUnmanagedDocument* pDocument)
{
}
Interface ISymUnmanagedDocument is private:
@dend, I haven't had a chance to address it yet ... I will probably resume this task tomorrow