Docfx: Merge metadata for class with same name found in multiple projects

[sandersaares]

DocFX Version Used:
2.28.3

Template used: (default or statictoc or contain custom template)
default

Steps to Reproduce:

I have a class named XYZ.ExtensionMethods in two projects, containing various generic extension methods (simplified scenario).

1. Create a class in two projects, with the same name and some contents (in my case, extension methods).
2. Build API documentation for the two projects as one DocFX project.

Expected Behavior:
Extension methods defined in both classes are visible in the generated documentation.

Actual Behavior:
Only one set of extension methods is visible. The following error is reported from DocFX build:

[17-12-18 06:14:31.987]Info:[MetadataCommand.ExtractMetadata]zzz.zzz.zzzalready exists in xxx.xxx, ignore current one
[17-12-18 06:14:31.988]Warning:[MetadataCommand.ExtractMetadata]Duplicate member xxx.xxx.xxx is found from ../../yyy/yyy.cs and ../../zzz.zzz/zzz.cs, use the one in ../../yyy/yyy.cs and ignore the one from ../../zzz.zzz/zzz.cs

I can also imagine some other possible scenarios where one might have a type with the same name in multiple projects (e.g. for targeting different platforms, when you know that they could not possibly be simultaneously loaded but you still want to offer the same name in the API).

[ahmeturganci]

I have some problem.

[vwxyzh]

@sandersaares what's the proposal for two class sharing same full name?
And for c# compiler this also don't work when your project reference both library.

[sandersaares]

@vwxyzh the OP outlines two scenarios where I foresee myself using such a construct - a container for extension methods and platform-specific libraries that are never loaded together. I suspect with enough innovation one could think of more.

[vwxyzh]

@sandersaares
For platform-specific libraries that are never loaded together,
I think the members are almost same for same class, and methods have same functional, then one API document is enough.

If different platform has different API set:

1. Use two metadata items for different platform.
2. Use docfx merge command to merge two implements with platform information.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[sandersaares]

This remains an important scenario.

[superyyrrzz]

Does what @vwxyzh suggested work for you? @sandersaares

[sandersaares]

I do not understand that suggestion. I do not know what "Use two metadata items" means - I just do "docfx build". How do I "use" a "metadata item", whatever that is?

[superyyrrzz]

It means to put 2 items into the metadata array, like:

{
  "metadata": [
    { /** src ... dest ... **/ },
    { /** src ... dest ... **/ }
  ]

This will ensure generate 2 set of metadata without conflict.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in a week if no further activity occurs.

[stale[bot]]

Closing this issue after a prolonged period of inactivity. If you still think this issue is relevant, please feel free to ping a maintainer or leave a comment.

[wouterroos]

Hi,

I'd like to re-open this issue as we're running into the same problem. We have extension methods extending the same type but are contained in different assemblies due to them extending on different aspects of the type which require certain dependencies, which are contained/referenced in these assemblies. This approach is identical to how Microsoft uses extension methods on, for example, ILoggingBuilder to add a specific type of logging (e.g. .AddConsole()). See this link for details on this specific case.

Thanks!