XML COmment woes in VS2005

[SteveCriscuoli]

I originally posted this in microsoft.public.xml ... my apologies to
those to who read both groups ...
Someone please tell me if I'm missing something here. The XML Comment
generator in VS2005 seems to be woefully incomplete. I created a test
solution with 2 classes in different namespaces

XTest.Derived.DerivedClass
XTest.Base.BaseClass

and yes, DerivedClass is dreived from BaseClass.

I gave them each 2 constructors, DerivedClass
received a method, a property, and a private field.

below is what I got:

<?xml version="1.0" ?>
- <doc>
- <assembly>
<name>XTest</name>
</assembly>
- <members>
- <member name="T:XTest.Derived.DerivedClass">
<summary>This is my derived class.</summary>
</member>
- <member name="T:XTest.Base.BaseClass">
<summary>comments for the entire class</summary>
</member>
- <member name="M:XTest.Base.BaseClass.#ctor">
<summary>default constructor comments.</summary>
</member>
- <member name="M:XTest.Base.BaseClass.#ctor(System.String)" >
<summary>alternate constructor comments</summary>
<param name="s">first parameter</param>
</member>
- <member name="F:XTest.Derived.DerivedClass.ia">
<summary>my array</summary>
</member>
- <member name="M:XTest.Derived.DerivedClass.#ctor">
<summary>default DC constructor</summary>
</member>
- <member name="M:XTest.Derived.DerivedClass.#ctor(System.St ring)">
<summary>alternate constructor for DC</summary>
<param name="s">same silly string</param>
</member>
- <member name="M:XTest.Derived.DerivedClass.getVal">
<summary>returns the value 19</summary>
<returns>the value 19</returns>
</member>
- <member name="P:XTest.Derived.DerivedClass.Ia">
<summary>accessor and mutator for ia.</summary>
</member>
</members>
</doc>

You'll notice there is no relation in here between the two classes. How
come?
How can anyone generate a sufficiently complete API document if you
can't
show class inheritance? I've combed through the MSDN site and can't
even
find a tag I could add to my documentation to 'help things along' which
I shouldn't
have to do in the first place.

Someone please enlighten me.

Steve
PS - I'll send you the whole solution if you send me an email

[Steve Barnett]

Don't know if this is going to solve your problem, but I've had some success
generating XML comments using GhostDoc:
http://www.roland-weigelt.de/ghostdoc/

It might help with your problem. I'm far too inexperienced to offer specific
advice, which is why I use tools like this!

Steve
"SteveCriscuoli" <st***************@gmail.com> wrote in message
news:11**********************@g10g2000cwb.googlegr oups.com...

I originally posted this in microsoft.public.xml ... my apologies to
those to who read both groups ...
Someone please tell me if I'm missing something here. The XML Comment
generator in VS2005 seems to be woefully incomplete. I created a test
solution with 2 classes in different namespaces

XTest.Derived.DerivedClass
XTest.Base.BaseClass

and yes, DerivedClass is dreived from BaseClass.

I gave them each 2 constructors, DerivedClass
received a method, a property, and a private field.

below is what I got:

<?xml version="1.0" ?>
- <doc>
- <assembly>
<name>XTest</name>
</assembly>
- <members>
- <member name="T:XTest.Derived.DerivedClass">
<summary>This is my derived class.</summary>
</member>
- <member name="T:XTest.Base.BaseClass">
<summary>comments for the entire class</summary>
</member>
- <member name="M:XTest.Base.BaseClass.#ctor">
<summary>default constructor comments.</summary>
</member>
- <member name="M:XTest.Base.BaseClass.#ctor(System.String)" >
<summary>alternate constructor comments</summary>
<param name="s">first parameter</param>
</member>
- <member name="F:XTest.Derived.DerivedClass.ia">
<summary>my array</summary>
</member>
- <member name="M:XTest.Derived.DerivedClass.#ctor">
<summary>default DC constructor</summary>
</member>
- <member name="M:XTest.Derived.DerivedClass.#ctor(System.St ring)">
<summary>alternate constructor for DC</summary>
<param name="s">same silly string</param>
</member>
- <member name="M:XTest.Derived.DerivedClass.getVal">
<summary>returns the value 19</summary>
<returns>the value 19</returns>
</member>
- <member name="P:XTest.Derived.DerivedClass.Ia">
<summary>accessor and mutator for ia.</summary>
</member>
</members>
</doc>

You'll notice there is no relation in here between the two classes. How
come?
How can anyone generate a sufficiently complete API document if you
can't
show class inheritance? I've combed through the MSDN site and can't
even
find a tag I could add to my documentation to 'help things along' which
I shouldn't
have to do in the first place.

Someone please enlighten me.

Steve
PS - I'll send you the whole solution if you send me an email

[Barry Kelly]

"SteveCriscuoli" <st***************@gmail.com> wrote:

Someone please tell me if I'm missing something here. The XML Comment
generator in VS2005 seems to be woefully incomplete. I created a test
solution with 2 classes in different namespaces

XTest.Derived.DerivedClass
XTest.Base.BaseClass

and yes, DerivedClass is dreived from BaseClass. [...] You'll notice there is no relation in here between the two classes. How
come?
How can anyone generate a sufficiently complete API document if you
can't show class inheritance? I've combed through the MSDN site and can't
even find a tag I could add to my documentation to 'help things along' which
I shouldn't have to do in the first place.

Someone please enlighten me.

The bit you're missing is System.Reflection. Existing tools like NDoc
require the assemblies as well as the XML, for this reason, AFAIK.
Basically, you can't do everything with just a transform.

-- Barry

--
http://barrkel.blogspot.com/

[SteveCriscuoli]

Yeah, That's what I was thinking. I also program in Java and really
love javadoc but I guess that's what it's doing as well. I just wish VS
had gone 'the extra mile' and finished the job.
Barry Kelly wrote:

"SteveCriscuoli" <st***************@gmail.com> wrote:

Someone please tell me if I'm missing something here. The XML Comment
generator in VS2005 seems to be woefully incomplete. I created a test
solution with 2 classes in different namespaces

XTest.Derived.DerivedClass
XTest.Base.BaseClass

and yes, DerivedClass is dreived from BaseClass.

[...]

You'll notice there is no relation in here between the two classes. How
come?
How can anyone generate a sufficiently complete API document if you
can't show class inheritance? I've combed through the MSDN site and can't
even find a tag I could add to my documentation to 'help things along' which
I shouldn't have to do in the first place.

Someone please enlighten me.

The bit you're missing is System.Reflection. Existing tools like NDoc
require the assemblies as well as the XML, for this reason, AFAIK.
Basically, you can't do everything with just a transform.

-- Barry

--
http://barrkel.blogspot.com/