Index

From: Claudio Friederich  TRI-L Data Systems, Inc.
Subject: Problems documenting Generics
Date: Mon, 28 Sep 2009 16:28:51 -1000
Newsgroup: steema.public.teegofer2.general  

There appear to be several problems with documenting Generics:

When documenting generic types and generic members, the syntax display is
inconsistent. Generic delegates listed in the table of types in the
namespace pages, as well as generic members in the table of members in the
type members pages, are displayed in a typename`number syntax rather than
your C#-like syntax that is used throughout the rest of the
program/documentation, and their hyperlinks do not work. Similarly, the
TypeName properties/methods/events toc headings, for generic types, display
the type name in the typename`number syntax rather than your proprietary
syntax used throughout the rest of the program. When a generic type (not a
generic type parameter, but a full generic type) is used as a parameter in a
method, in said method's syntax display, the parameter type is also listed
in the typename`number syntax rather than your syntax.

When documenting generic delegates defined within types, the documentation
does not appear to work. Generic delegates defined within a type, in the
generated toc, are displayed as the name of their containing type, and the
toc entry takes you to the containing type, while the documentation for the
delegate is missing altogether.

The long and short of it appears to be that 1) generic delegates defined
within types have a problem, and 2) that the C# like syntax you use in the
syntax panels in member pages is not used consistently throughout the
documentation when generics are involved (while this is cosmetic, it matters
because it will confuse the users if the documentation uses two different
syntaxes for no apparent reason, especially since generic syntax can get
complicated to begin with).

Claudio Friederich
CICClaudio@aol.com