Wanted in C# 2.0: Namespace documentation

  • Thread starter Thread starter Jon Davis
  • Start date Start date
J

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
 
Namespaces don't have <summary> documentation (do they?), and I think it
would be nice to have it.
Click to expand...

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.
 
Christoph Nahr said:
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.
Click to expand...

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

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

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?
 
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
 
Christoph said:
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.
Click to expand...

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.
 
Colin said:
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.
Click to expand...

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.
 
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.
Click to expand...

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.
 
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
 
Christoph said:
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.
Click to expand...

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.
 
Back
Top