Bug 16344 - monodoc needs to merge namespace type listings
Summary: monodoc needs to merge namespace type listings
Status: NEEDINFO
Alias: None
Product: Tools
Classification: Mono
Component: Doctools ()
Version: unspecified
Hardware: PC Mac OS
: --- normal
Target Milestone: ---
Assignee: Jonathan Pryor
URL:
Depends on:
Blocks:
 
Reported: 2013-11-19 13:35 UTC by Jonathan Pryor
Modified: 2015-11-04 16:06 UTC (History)
1 user (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 for Bug 16344 on GitHub or Developer Community if you have new information to add and do not yet see a matching new report.

If the latest results still closely match this report, you can use the original description:

  • Export the original title and description: GitHub Markdown or Developer Community HTML
  • Copy the title and description into the new report. Adjust them to be up-to-date if needed.
  • Add your new information.

In special cases on GitHub you might also want the comments: GitHub Markdown with public comments

Related Links:
Status:
NEEDINFO

Description Jonathan Pryor 2013-11-19 13:35:19 UTC
Namespaces can be split across multiple namespaces. Unfortunately, when rendering an N:Namespace URL, only the first loaded "documentation source" is used to list types in the namespace.

For example, consider the System.IO namespace:

http://androidapi.xamarin.com/?link=N%3aSystem.IO

At present, it lists one type: AndroidExtensions. Compare to the tens of types listed at:

http://msdn.microsoft.com/en-us/library/system.io.aspx
Comment 1 Joel Martinez 2015-11-04 15:32:04 UTC
Totally agree that this needs a better implementation ... but how would it work? What would we show on the navigation stack on the left? 

One possible idea that I've been kicking around is to start including an identifier for the doc set of a given "cref url". so for example, https://developer.xamarin.com/api/docset/bcl/namespace/System.IO ... so in that case, you'd know exactly what node to show.

Thoughts?
Comment 2 Jonathan Pryor 2015-11-04 16:06:07 UTC
This bug presupposes a worldview which we've moved away from. (Perhaps we should move back?)

> What would we show on the navigation stack on the left?

The "older" worldview was one of *unification* and *duplication*. (Wait, what?)

OK, confusing phrasing. The previous worldview was *product-centric*.

Here's an example: androidapi.xamarin.com previously showed both *all* ("all") the types in Xamarin.Android and *only* the types in Xamarin.Android.

Meaning androidapi.xamarin.com had a System namespace, a System.Xml namespace, etc., representing the union of all types in all assemblies shipped with Xamarin.Android, and *only* those types. For example, it would NOT show System.CodeDom.Compiler.CodeCompiler, because that type doesn't exist in Xamarin.Android.

The documentation was thus a reliable way of telling what types and members Xamarin.Android actually supported, because androidapi.xamarin.com ONLY showed types and members in Xamarin.Android.

Which is also why this worldview was predicated on duplication: Xamarin.iOS had one copy, Xamarin.Android had a slightly different copy, Desktop mono had another copy... lots of duplication across products.

That is no longer the case, but that is the worldview that this bug presupposed.

(I'd also like to RETURN to that world. Really.)

In the context of that former worldview, the bug was that when viewing the documentation node for System.IO, only the type System.IO.AndroidExtensions was shown, and no other types, which is very dumb.

The *desired* result was that *all* types from *all* providers that understood and provided types in the System.IO namespace would appear in the N:System.IO documentation node, e.g. System.IO.Stream in addition to AndroidExtensions.

> how would it work

Plausibly, instead of looping through all HelpSources, calling HelpSource.RenderUrl(), and returning the contents of the first HelpSource that returned a non-null string, we'd instead go through all of them and *merge* the contents.

Which in turn suggests that RenderUrl() isn't the right API; instead, we'd want to ask the HelpSource for all types in a namespace, e.g. GetTypesInNamespace(), and then we could render all of them together (somehow).

> One possible idea that I've been kicking around is to start including an
> identifier for the doc set of a given "cref url". so for example,
> https://developer.xamarin.com/api/docset/bcl/namespace/System.IO ... so in that
> case, you'd know exactly what node to show.

This is working in the New worldview, when I rather like the older one. :-)

Rephrased: *I* don't want *just* a "BCL docset", which is what we have now.

I want a Xamarin.Android docset which shows the union of Xamarin.Android-specific types and members *merged with* the BCL members present within Xamarin.Android, and *only* Xamarin.Android. Meaning System.CodeDom would NOT be shown (except for the *two* types in Xamarin.Android's System.dll, which I'll now ignore.)

Rephrased: how am I, as a user, supposed to tell which types and members are in Xamarin.Android *without* opening an IDE and actually trying to build something? (Why would I do that? Support, for starters. It's quite nice to say "Xamarin.Android doesn't support that method -- see, it's not in the docs!" as opposed to "It doesn't build".)