XML Comments and Reflection

  • Thread starter Thread starter John Wood
  • Start date Start date
J

John Wood

Does anyone know how to programmatically retrieve a method's XML comments
through reflection or any other run-time means?

I actually always thought that the description you put in comments was
automatically put into the DescriptionAttribute, but after testing this
doesn't seem to be the case...
 
Hi Rakesh,
Thanks for your reply.
nDoc seems to process the XML that's exported from a Visual Studio
project... so no luck there.

It seems elusive... how do you extract the summary comments from an
assembly?!
 
John Wood said:
Thanks for your reply.
nDoc seems to process the XML that's exported from a Visual Studio
project... so no luck there.

It seems elusive... how do you extract the summary comments from an
assembly?!
Click to expand...

They're not *in* the assembly - they're only in the .xml file.
 
I'm beginning to think you're right.
Why did they do it that way? Wouldn't it have made more sense to have
included the descriptions as attributes as part of the metadata? Even in COM
they did it this way, putting the information into the type library... seems
pretty stupid to have it separate to the DLL like that.
 
John Wood said:
I'm beginning to think you're right.
Why did they do it that way? Wouldn't it have made more sense to have
included the descriptions as attributes as part of the metadata? Even in COM
they did it this way, putting the information into the type library...
Click to expand...

What information, exactly? Documentation? That doesn't sound right to
me, although I admit I'm not a COM expert by any means.
seems pretty stupid to have it separate to the DLL like that.
Click to expand...

Let me be clear - attributes *are* in the assembly. It's only the XML
documentation which isn't. That makes sense, because it's really for
human use. While it makes sense to ship it with an SDK, it makes sense
*not* to ship it with an end-user product. Well-written documentation
can easily end up being as large as the assembly itself. For non-
developers, it's completely useless - so why include it?
 
Hi John:

I guess you are referring to the helpstring attribute which shipped as
part of the type libary:

__interface IBar : IDispatch
{
[id(1), helpstring("This method does Foo")]
HRESULT Foo([in] BSTR param1);
}

I personally never found these brief descriptions very informative,
but I can imagine some people might have put some work into them to
make them useful.

You could do something similar with CustomAttributes, or perhaps write
a macro or plugin to add XML comments into a DescriptionAttribute, but
I don't know of any existing tools that would utilize this information
from an assembly (unless you are building COM visible types...)
 
I guess you are referring to the helpstring attribute which shipped as
part of the type libary:
Click to expand...

Right. The type library is an optional resource in a module, and the
helpstring is useful for things like intellisense and the object browser. I
can't imagine anyone would say that intellisense descriptions aren't useful?

The good thing about type libraries is that they can be removed from the
component modules before they are released, as they're just resources (in
the case of most apps anyway).

--
John Wood
EMail: first name, dot, second name at priorganize.com


Scott Allen said:
Hi John:

I guess you are referring to the helpstring attribute which shipped as
part of the type libary:

__interface IBar : IDispatch
{
[id(1), helpstring("This method does Foo")]
HRESULT Foo([in] BSTR param1);
}

I personally never found these brief descriptions very informative,
but I can imagine some people might have put some work into them to
make them useful.

You could do something similar with CustomAttributes, or perhaps write
a macro or plugin to add XML comments into a DescriptionAttribute, but
I don't know of any existing tools that would utilize this information
from an assembly (unless you are building COM visible types...)

--
Scott
http://www.OdeToCode.com/

I'm beginning to think you're right.
Why did they do it that way? Wouldn't it have made more sense to have
included the descriptions as attributes as part of the metadata? Even in COM
they did it this way, putting the information into the type library... seems
pretty stupid to have it separate to the DLL like that.
Click to expand...
Click to expand...
 
although I admit I'm not a COM expert by any means. <<

So what were you doing before .net came along?
Assuming you're older than, say, 5 ;)
 
John Wood said:
Right. The type library is an optional resource in a module, and the
helpstring is useful for things like intellisense and the object browser.
Click to expand...

If you want to use intellisense and the object browser, just supply the
XML file.
I can't imagine anyone would say that intellisense descriptions aren't
useful?
Click to expand...

They're useful to developers, so you supply the XML file to developers,
but not to end users.
The good thing about type libraries is that they can be removed from the
component modules before they are released, as they're just resources (in
the case of most apps anyway).
Click to expand...

I think I'd rather have the files separate to start with, myself, so
that the assembly the developer uses is *exactly* the same assembly
that the user uses.
 
Back
Top