Per the email conversation we had:
Nickolas,
I guess I would (expectedly) disagree. There shouldn't need to be a
coupling between what makes it into the assembly - it's for
documentation. For that matter, I'd go so far as to say the IDE should
have a simple editor that would allow you to add your own comment tags.
This is about documentation, not compiled code - I want to be able to
organize a documented view of source code that would allow me to
"outline" the comments in XML/HTML in the same way I can outline in
the IDE. I'd say the fact that such user defined comments or a <region>
tag would have no compiled presence or utility is less than relevant
compared to what they add to the documentation...
Joseph
-----Original Message-----
From: Nicholas Paldino [mailto:ni**********@exisconsulting.com]
Sent: Fri 6/2/2006 2:00 PM
To: Joseph E. Healy
Cc:
Subject: RE: Self documenting regions - would be nice...
Joseph,
I understand what you are getting at, but the XML documentation
in
this case would be used by the IDE exclusively (it doesn't make sense
for it
to be used elsewhere, since the regions are compiled out of the code).
The thing is, the VS.NET IDE uses the assembly, along with the
XML
documentation to provide feedback in the IDE. While the XML comments
could
make it into the XML documentation, the ide would not be able to do
anything
with them, since they do not link up with anything in the compiled
assembly.
I would just place regular comments in the code itself, since
that
is the only place where regions are applicable.
- Nick
-----Original Message-----
From: Joseph E. Healy [mailto:jo**********@AvaSys.com]
Sent: Friday, June 02, 2006 4:57 PM
To: Nicholas Paldino
Subject: RE: Self documenting regions - would be nice...
Nicholas,
The issue is, being an organization freak and to allow me to navigate
code
with the outlining key functions, I use regions pretty extensively. I
have
template that essentially looks more or less like this that I use for
my
code and I'd like the region comments to show up in the xml comments...
- Joseph
namespace namespace.foo
{
#region (REFERENCES)
#endregion
#region (CLASSES, PUBLIC)
public class foo
{
#region (CONSTANTS, PRIVATE)
#endregion
#region (MEMBERS, VALUE, PRIVATE)
#endregion
#region (MEMEBERS, REFERENCE, PRIVATE)
#endregion
#region (PROPERTIES, PUBLIC)
#endregion
#region (DELEGATES, PUBLIC)
#endregion
#region (CONSTRUCTORS, PUBLIC)
#endregion
#region (METHODS, PUBLIC)
#endregion
#region (METHODS, HELPER, PRIVATE)
#endregion
#region (METHODS, DELEGATE, PUBLIC)
#endregion
#region (DESTRUCTOR, PUBLIC)
#endregion}
#endregion
#region (CLASSES_BASE, ABSTRACT, PUBLIC)
#endregion
#region (INTERFACES, PUBLIC)
#endregion
}
-----Original Message-----
From: Nicholas Paldino [mailto:ni**********@exisconsulting.com]
Sent: Fri 6/2/2006 1:44 PM
To:
ex********@gmail.com
Cc:
Subject: Re: Self documenting regions - would be nice...
Spleenwort,
The problem with that is that no tool would be able to use
it.
#region
directives are compiled out of the code, they have no effect on
the
outcome.
Also, compiled code doesn't have a direct relation in terms of
position to
the original typed code. Because of this, where would you put
the
region in
the compiled assembly?
You could try and put something in there, but I don't know
how
you would
know to do anything with it.
--
- Nicholas Paldino [.NET/C# MVP]
-
mv*@spam.guard.caspershouse.com
"Spleenwort" <ex********@gmail.com> wrote in message
news:11**********************@f6g2000cwb.googlegro ups.com...
With regard to XML comments in c#.
I think that #regions should be self-documenting relative to
XML comments or that a <region> tag should be defined and
auto-inserted when you type #region (blah, blah).
Anyone have any suggestions for having regions and their
comments
show up in XML comments...
