Wanted in C# 2.0: Namespace documentation

[Jon Davis]

Namespaces don't have <summary> documentation (do they?), and I think it
would be nice to have it. For instance,

/// <summary>
/// Classes containing math functions.
/// </summary>
namespace BillyBob.Math {
...
}

Now if you had more than one <summary> compiled with a namespace, such as
having two class files each with a different <summary> for its otherwise
identical namespace, then the consumer could be able to cycle through the
different summary descriptions... it should be an array of descriptions.

Might be a little messy I suppose, but it's better than no descriptions at
all.

Sometimes people deliver things in the strangest namespaces ...

Jon

[Christoph Nahr]

On Tue, 18 May 2004 23:16:09 -0700, "Jon Davis"
<jo*@REMOVE.ME.jondavis.net> wrote:

Namespaces don't have <summary> documentation (do they?), and I think it
would be nice to have it.

Agreed. The standard excuse why they don't exist yet is that a
namespace declaration typically appears in many different files, so
the compiler might get confused by multiple summary tags.

Personally I think that's easy enough to resolve by simply taking the
last summary tag found, and ignoring all others while emitting a
warning. It's the programmer's responsibility to only use one tag.
--
http://www.kynosarges.de

[Niki Estner]

"Christoph Nahr" <ch************@kynosarges.de> wrote in
news:lb********************************@4ax.com...

On Tue, 18 May 2004 23:16:09 -0700, "Jon Davis"
<jo*@REMOVE.ME.jondavis.net> wrote:

Namespaces don't have <summary> documentation (do they?), and I think it
would be nice to have it.

Agreed. The standard excuse why they don't exist yet is that a
namespace declaration typically appears in many different files, so
the compiler might get confused by multiple summary tags.

I've read that classes could be spread over multiple files in C# 2 -
wouldn't that cause exactly the same confusion?

Niki

[Christoph Nahr]

On Wed, 19 May 2004 10:00:48 +0200, "Niki Estner"
<ni*********@cube.net> wrote:

I've read that classes could be spread over multiple files in C# 2 -
wouldn't that cause exactly the same confusion?

Yes, it would. I don't know what the proposed solution for this case
is -- maybe there's a distinction between a "main class file" and
"continuation" class files, and only the main file can have comments?
--
http://www.kynosarges.de

[Colin Young]

Actually, you can document namespaces already, but it needs to be done in an
external file IIRC. I don't remember if the MS tools can use it, or if you
need to use NDoc. If you do a bit of a search, you should be able to find
some information about it. Unfortunately the project where I used it was 2
computers ago and I don't seem to have put my build scripts and the
namespace documentation into source control.

If I find more info, I'll post it to this thread.

Colin

"Jon Davis" <jo*@REMOVE.ME.jondavis.net> wrote in message
news:eg**************@TK2MSFTNGP12.phx.gbl...

Namespaces don't have <summary> documentation (do they?), and I think it
would be nice to have it. For instance,

/// <summary>
/// Classes containing math functions.
/// </summary>
namespace BillyBob.Math {
...
}

Now if you had more than one <summary> compiled with a namespace, such as
having two class files each with a different <summary> for its otherwise
identical namespace, then the consumer could be able to cycle through the
different summary descriptions... it should be an array of descriptions.

Might be a little messy I suppose, but it's better than no descriptions at
all.

Sometimes people deliver things in the strangest namespaces ...

Jon

[mikeb]

Christoph Nahr wrote:

On Tue, 18 May 2004 23:16:09 -0700, "Jon Davis"
<jo*@REMOVE.ME.jondavis.net> wrote:

Namespaces don't have <summary> documentation (do they?), and I think it
would be nice to have it.

Agreed. The standard excuse why they don't exist yet is that a
namespace declaration typically appears in many different files, so
the compiler might get confused by multiple summary tags.

Personally I think that's easy enough to resolve by simply taking the
last summary tag found, and ignoring all others while emitting a
warning. It's the programmer's responsibility to only use one tag.

I think a potentially bigger problem is that namespaces don't really
exist in .NET except as a logical entity. As far as the framework is
concerned, each class has a unique name and it's simply a matter of
convenience that some portion at the beginning happens to match that of
other classes.

Note that the classes don't even need to reside in the same assembly to
be members of the same namespace.

--
mikeb

[mikeb]

Colin Young wrote:

Actually, you can document namespaces already, but it needs to be done in an
external file IIRC. I don't remember if the MS tools can use it, or if you
need to use NDoc. If you do a bit of a search, you should be able to find
some information about it. Unfortunately the project where I used it was 2
computers ago and I don't seem to have put my build scripts and the
namespace documentation into source control.

If I find more info, I'll post it to this thread.
I did a quick look, and indeed NDoc has an option
(UseNamespaceDocSummaries) that allows you to provide XML documentation
for namespaces by including the doc comments for a class named
"NamespaceDoc" in documentation.

The class is required because the C# compiler will only generate XML doc
output for types and members.

Colin

"Jon Davis" <jo*@REMOVE.ME.jondavis.net> wrote in message
news:eg**************@TK2MSFTNGP12.phx.gbl...

Namespaces don't have <summary> documentation (do they?), and I think it
would be nice to have it. For instance,

/// <summary>
/// Classes containing math functions.
/// </summary>
namespace BillyBob.Math {
...
}

Now if you had more than one <summary> compiled with a namespace, such as
having two class files each with a different <summary> for its otherwise
identical namespace, then the consumer could be able to cycle through the
different summary descriptions... it should be an array of descriptions.

Might be a little messy I suppose, but it's better than no descriptions at
all.

Sometimes people deliver things in the strangest namespaces ...

Jon

--
mikeb

[Christoph Nahr]

On Wed, 19 May 2004 13:57:38 -0700, mikeb
<ma************@nospam.mailnull.com> wrote:

I think a potentially bigger problem is that namespaces don't really
exist in .NET except as a logical entity. As far as the framework is
concerned, each class has a unique name and it's simply a matter of
convenience that some portion at the beginning happens to match that of
other classes.

True, but the assembly structure isn't really relevant here since XML
documentation isn't stored with the assemblies anyway. I don't expect
the IDE to associate namespace comments with assemblies or anything;
the compiler should just output them into its XML documentation
whenever it comes across them, so that they can be used by some
external tool like NDoc to build the class reference.
--
http://www.kynosarges.de

[Jon Davis]

Colin,

The documentation advantage I was seeking was in having a description of the
namespaces while paging through the intellisense menus. It should be
integrated in the assembly.

Jon
"Colin Young" <[e-mail]> wrote in message
news:Ot*************@TK2MSFTNGP10.phx.gbl...

Actually, you can document namespaces already, but it needs to be done in an external file IIRC. I don't remember if the MS tools can use it, or if you
need to use NDoc. If you do a bit of a search, you should be able to find
some information about it. Unfortunately the project where I used it was 2
computers ago and I don't seem to have put my build scripts and the
namespace documentation into source control.

If I find more info, I'll post it to this thread.

Colin

"Jon Davis" <jo*@REMOVE.ME.jondavis.net> wrote in message
news:eg**************@TK2MSFTNGP12.phx.gbl...

Namespaces don't have <summary> documentation (do they?), and I think it
would be nice to have it. For instance,

/// <summary>
/// Classes containing math functions.
/// </summary>
namespace BillyBob.Math {
...
}

Now if you had more than one <summary> compiled with a namespace, such as having two class files each with a different <summary> for its otherwise
identical namespace, then the consumer could be able to cycle through the different summary descriptions... it should be an array of descriptions.

Might be a little messy I suppose, but it's better than no descriptions at all.

Sometimes people deliver things in the strangest namespaces ...

Jon

[Colin Young]

That actually would be useful (although less useful than sensibly named
namespaces). Probably best to submit that through the product suggestion
page:

http://register.microsoft.com/mswish/suggestion.asp

You could also hope that one of the developers sees the message here.

Colin

"Jon Davis" <jo*@REMOVE.ME.jondavis.net> wrote in message
news:%2****************@TK2MSFTNGP12.phx.gbl...

Colin,

The documentation advantage I was seeking was in having a description of the namespaces while paging through the intellisense menus. It should be
integrated in the assembly.

Jon
"Colin Young" <[e-mail]> wrote in message
news:Ot*************@TK2MSFTNGP10.phx.gbl...

Actually, you can document namespaces already, but it needs to be done in

an

external file IIRC. I don't remember if the MS tools can use it, or if you need to use NDoc. If you do a bit of a search, you should be able to find some information about it. Unfortunately the project where I used it was 2 computers ago and I don't seem to have put my build scripts and the
namespace documentation into source control.

If I find more info, I'll post it to this thread.

Colin

"Jon Davis" <jo*@REMOVE.ME.jondavis.net> wrote in message
news:eg**************@TK2MSFTNGP12.phx.gbl...

Namespaces don't have <summary> documentation (do they?), and I think it would be nice to have it. For instance,

/// <summary>
/// Classes containing math functions.
/// </summary>
namespace BillyBob.Math {
...
}

Now if you had more than one <summary> compiled with a namespace, such

as having two class files each with a different <summary> for its otherwise identical namespace, then the consumer could be able to cycle through the different summary descriptions... it should be an array of descriptions.
Might be a little messy I suppose, but it's better than no

descriptions at all.

Sometimes people deliver things in the strangest namespaces ...

Jon

[mikeb]

Christoph Nahr wrote:

On Wed, 19 May 2004 13:57:38 -0700, mikeb
<ma************@nospam.mailnull.com> wrote:

I think a potentially bigger problem is that namespaces don't really
exist in .NET except as a logical entity. As far as the framework is
concerned, each class has a unique name and it's simply a matter of
convenience that some portion at the beginning happens to match that of
other classes.

True, but the assembly structure isn't really relevant here since XML
documentation isn't stored with the assemblies anyway. I don't expect
the IDE to associate namespace comments with assemblies or anything;
the compiler should just output them into its XML documentation
whenever it comes across them, so that they can be used by some
external tool like NDoc to build the class reference.

My use of the word 'problem' is too strong. It's really just something
to be aware of for whoever might implement or use XML doc tags for
namespaces. There's a fair amount of confusion out there (particularly
with people new to .NET) that namespaces are something more than they
are - for example, that they're tied to an assembly or that they have
something to do with the class hierarchy.

Note that at times, the XML docs are used on an assembly basis; VS.NET's
Intellisense picks up information from an appropriately named XML file
when an assembly is referenced for some of the information it displays.

--
mikeb