By using this site, you agree to our updated Privacy Policy and our Terms of Use. Manage your Cookies Settings.
443,730 Members | 1,480 Online
Bytes IT Community
+ Ask a Question
Need help? Post your question and get tips & solutions from a community of 443,730 IT Pros & Developers. It's quick & easy.

Self documenting regions - would be nice...

P: n/a
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...

Jun 2 '06 #1
Share this Question
Share on Google+
8 Replies


P: n/a
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...

Jun 2 '06 #2

P: n/a
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...


Jun 3 '06 #3

P: n/a
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
}

Jun 3 '06 #4

P: n/a
>From Nicholas' email:

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

Jun 3 '06 #5

P: n/a
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

Jun 3 '06 #6

P: n/a
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
}

Jun 3 '06 #7

P: n/a
>From Nicholas' email:

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

Jun 3 '06 #8

P: n/a
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

Jun 3 '06 #9

This discussion thread is closed

Replies have been disabled for this discussion.