#453 J# assemblies cant be documented

[webrant]

The full typename is not generated for J# generated
documentation files causing nDOC to miss the methods.

J# example:

package JSharp;

/**
* String help class
*/
public class StringHelper
{
/**
* Construct
*/
public StringHelper()
{
}

/**
* Combine two strings
* @param part1 Part 1
* @param part2 Part 2
* @return The combined string
*/
public String Combine(String part1, String part2)
{
return part1 + part2;
}
}

will generate

<?xml version="1.0"?>
<doc>
<assembly>
<name>JSharp</name>
</assembly>
<members>
<member name="T:JSharp.StringHelper">
<remarks>String help class</remarks>
</member>
<member name="M:JSharp.StringHelper.#ctor">
<summary>Construct</summary>
</member>
<member
name="M:JSharp.StringHelper.Combine(String,String)">
<summary>Combine two strings</summary>
<param name="part1">Part 1</param>
<param name="part2">Part 2</param>
<returns>The combined string</returns>
</member>
</members>
</doc>

The same code in C# generates
<?xml version="1.0"?>
<doc>
<assembly>
<name>CSharp</name>
</assembly>
<members>
<member name="T:CSharp.StringHelper">
<summary>
String help class
</summary>
</member>
<member name="M:CSharp.StringHelper.#ctor">
<summary>
Construct
</summary>
</member>
<member
name="M:CSharp.StringHelper.Combine(System.String,System.String)">
<summary>
Combine two strings
</summary>
<param name="part1">Part 1</param>
<param name="part2">Part 2</param>
<returns>The combined string</returns>
</member>
</members>
</doc>

[webrant]

Test solution

[Kevin Downs]

Logged In: YES
user_id=919791

As you pointed out, this is a bug in J#... As such, there
is little or nothing we can do to resolve the issue;
without the full signature, NDoc cannot match
documentation against the assembly metadata. I suppose
NDoc could be modified to 'best guess' the match, but I
think this would be at best a hack and at worst produce
incorrect documentation :-(

I would suggest raising a bug report on the MSDN product
feedback site
http://lab.msdn.microsoft.com/productfeedback/default.aspx

Unfortunately, this is not the only problem with the j#
xml docs implementation - IIRC, there are two other issues.

1. summary comments (ie those without @tag) are trucated
after the first sentence. A more logical process would
have been to route the first sentence to <summary> and the
remainder to <remarks>.
2. summary comments are directed to the <remarks> tag on
types. This is an good example of following a (vaguely
worded) spec rather than looking at how tags are used in
the 'real world'. Apart from the dificulties this
implementation poses for NDoc, the produced xml files are
also useless for Intellisense; it never uses the <remarks>
tag!

[SourceForge Robot]

Logged In: YES
user_id=1312539

This Tracker item was closed automatically by the system. It was
previously set to a Pending status, and the original submitter
did not respond within 14 days (the time period specified by
the administrator of this Tracker).