[Mono-docs-list] Differences between generic names in the documentation.

[Valentin Sawadski]

On Mon, 2007-12-10 at 14:04 -0500, Jonathan Pryor wrote: 
> On Mon, 2007-12-10 at 17:57 +0100, Valentin Sawadski wrote:
> > By the way I think it should be pretty easy to extend monodocer to
> > generate <TypeSignature /> and <MemberSignature /> tags for different
> > languages. (Like MS does within their docs) This could probably be done
> > by using Mono.Addins so that 3rd party language developers could also
> > integrate their language to the docs. (Especially Boo, VB.NET and
> > Nemerle)
> 
> This should currently be pretty trivial -- just create a subclass of
> MemberFormatter for your particular language and call your new formatter
> in "the appropriate places."  This could be done much easier, but the
> fact that we currently already have an abstraction in place to generate
> these signature strings helps immensely.
> 
> Using Mono.Addins is also an interesting idea, though I'm not sure how
> useful it would be.  The reason being that <TypeSignature/> and
> <MemberSignature/> are generated at `monodocer` runtime, and the system
> that `monodocer` is run on may not have the plugins you desire.

That's what I've been thinking. Just to override MemberFormatter and
then using Mono.Addins to check at runtime which derived classes are
available to use them to generate the signatures.

Missing dependencies should not be a problem we would just have to ship
Mono.Addins and a couple of stock Formatters with monodoc. If users want
to use a different formatter they could add a additional addin into some
~/.config folder and Mono.Addins could load and use them as well.

This would be a pretty easy solution to enable multiple signatures
however this has the limitation that signatures are only created during
the creation of the documentation.

> What would make more sense -- though I have no idea how easy this would
> be -- is to alter the docbrowser to use Mono.Addins and have an XML ->
> signature addin for each language.  We'd likely need to extend the XML
> syntax further -- we have a <TypeParameter/> element but it's only used
> at class level, and it should likely be inserted at member level as well
> for generic methods -- but this would allow users to install addins on
> their local machine and have the XML signatures translated "on-the-fly"
> to their desired language.
> 
> The downside is that the XML contains C#-formatted type names (see other
> message for reasons why this won't change), so this effectively requires
> a C# -> language translator as well in some circumstances, but for the
> basics of member name, method parameters, type parameters, etc., this is
> all readily extractable from the XML.

I don't know much about how the browser parses his data but this is also
an alternative worth investigating. I'll probably look into both if I
have the time.

Kind Regards,
Valentin