Re-using XML comments

[Clive Dixon]

It's a bit of a PITA to duplicate XML comments in such a scenario as where
you want to give a class method implementing an interface method exactly the
same documentation (or part thereof) as the interface method, and keep them
in synch.

Are there any documentation tools, possibly using custom tags, available
which can support such a
feature?

 

[Nicholas Paldino [.NET/C# MVP]]

Clive,

I agree with you 100% that it is a pain to do this. Unfortunately,
there is nothing like a "reference" to other XML comments that I am aware
of. You would need a third party tool to handle all of this

This is also desirable for overloaded methods where the description is
the same, but the parameters differ slightly.

Hope this helps.

 

[Clive Dixon]

I guess it must be possible using NDoc's extensibility features, but that
would be a project in itself (especially as I'm far from an XSLT expert).

Let's hope for improved support in C# 3.0...

Clive,

I agree with you 100% that it is a pain to do this. Unfortunately,
there is nothing like a "reference" to other XML comments that I am aware
of. You would need a third party tool to handle all of this

This is also desirable for overloaded methods where the description is
the same, but the parameters differ slightly.

Hope this helps.


--
- Nicholas Paldino [.NET/C# MVP]
- (e-mail address removed)

It's a bit of a PITA to duplicate XML comments in such a scenario as
where
you want to give a class method implementing an interface method exactly
the
same documentation (or part thereof) as the interface method, and keep
them in synch.

Are there any documentation tools, possibly using custom tags, available
which can support such a
feature?

 

[Nicholas Paldino [.NET/C# MVP]]

Clive,

Fortunately, there is a way for your voice to be heard:

http://lab.msdn.microsoft.com/productfeedback/default.aspx

Put in a recommendation (or support an existing one that suits your
needs), and it will be entered into their internal system.


--
- Nicholas Paldino [.NET/C# MVP]
- (e-mail address removed)

I guess it must be possible using NDoc's extensibility features, but that
would be a project in itself (especially as I'm far from an XSLT expert).

Let's hope for improved support in C# 3.0...

Clive,

I agree with you 100% that it is a pain to do this. Unfortunately,
there is nothing like a "reference" to other XML comments that I am aware
of. You would need a third party tool to handle all of this

This is also desirable for overloaded methods where the description is
the same, but the parameters differ slightly.

Hope this helps.


--
- Nicholas Paldino [.NET/C# MVP]
- (e-mail address removed)

It's a bit of a PITA to duplicate XML comments in such a scenario as
where
you want to give a class method implementing an interface method exactly
the
same documentation (or part thereof) as the interface method, and keep
them in synch.

Are there any documentation tools, possibly using custom tags, available
which can support such a
feature?

 

[Kevin Spencer]

Use the <include> tag to include external file comments. This way you can
include the same comments for multiple items.

See:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vclrfinclude.asp
--
HTH,

Kevin Spencer
Microsoft MVP
..Net Developer
Who is Mighty Abbott?
A twin turret scalawag.

I guess it must be possible using NDoc's extensibility features, but that
would be a project in itself (especially as I'm far from an XSLT expert).

Let's hope for improved support in C# 3.0...

Clive,

I agree with you 100% that it is a pain to do this. Unfortunately,
there is nothing like a "reference" to other XML comments that I am aware
of. You would need a third party tool to handle all of this

This is also desirable for overloaded methods where the description is
the same, but the parameters differ slightly.

Hope this helps.


--
- Nicholas Paldino [.NET/C# MVP]
- (e-mail address removed)

It's a bit of a PITA to duplicate XML comments in such a scenario as
where
you want to give a class method implementing an interface method exactly
the
same documentation (or part thereof) as the interface method, and keep
them in synch.

Are there any documentation tools, possibly using custom tags, available
which can support such a
feature?

 

[Nick Hounsome]

The problem with <include> and with any scheme for referencing comments
somewhere else is that they are far more likely to become out of step with
the code than those actually with the method for 2 reasons:

1) Nobody looking at the method will bother checking that the comments are
correct if they are somewhere else.
2) Nobody changing the "primary" comment will ever look for all the places
in which it is used to ensure that it still holds.

I think copy and paste is probably the best of a bad set of options.

Use the <include> tag to include external file comments. This way you can
include the same comments for multiple items.

See:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vclrfinclude.asp
--
HTH,

Kevin Spencer
Microsoft MVP
.Net Developer
Who is Mighty Abbott?
A twin turret scalawag.

I guess it must be possible using NDoc's extensibility features, but that
would be a project in itself (especially as I'm far from an XSLT expert).

Let's hope for improved support in C# 3.0...

Clive,

I agree with you 100% that it is a pain to do this. Unfortunately,
there is nothing like a "reference" to other XML comments that I am
aware of. You would need a third party tool to handle all of this

This is also desirable for overloaded methods where the description
is the same, but the parameters differ slightly.

Hope this helps.


--
- Nicholas Paldino [.NET/C# MVP]
- (e-mail address removed)

message It's a bit of a PITA to duplicate XML comments in such a scenario as
where
you want to give a class method implementing an interface method
exactly the
same documentation (or part thereof) as the interface method, and keep
them in synch.

Are there any documentation tools, possibly using custom tags,
available which can support such a
feature?

 

[Bruce Wood]

This particular scenario wasn't mentioned, but someone did ask Anders
Hejlsberg at PDC'05 whether there shouldn't be some way to share
comments between overloads. Anders thought it was a good idea, although
I don't know that it was recorded anywhere.

So, if you put in a suggestion to that effect, it's likely to get a
favourable reception.