Donate Share

NDoc

Tracker: Bugs

5 J# assemblies cant be documented - ID: 1371701
Last Update: Settings changed ( kdowns )

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 ( webrant ) - 2005-12-02 13:46

5

Open

Wont Fix

Kevin Downs

NDoc Core

v1.3

Public


Comments ( 2 )

Date: 2006-01-10 03:21
Sender: sf-robotSourceForge.net Site Admin

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).


Date: 2005-12-02 15:07
Sender: kdownsProject AdminAccepting Donations

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!



Attached File ( 1 )

Filename Description Download
NDOCTest.zip Test solution Download

Changes ( 9 )

Field Old Value Date By
close_date 2006-01-10 03:21 2006-01-10 07:43 kdowns
status_id Closed 2006-01-10 07:43 kdowns
close_date 2005-12-02 15:07 2006-01-10 03:21 sf-robot
status_id Pending 2006-01-10 03:21 sf-robot
close_date - 2005-12-02 15:07 kdowns
assigned_to nobody 2005-12-02 15:07 kdowns
resolution_id None 2005-12-02 15:07 kdowns
status_id Open 2005-12-02 15:07 kdowns
File Added 158387: NDOCTest.zip 2005-12-02 13:53 webrant