#266 Type from external dll causes problems
NDoc 1.3
MS 1.1
MSDN
Using VBCommenter
Issue:-->
Sample code shown below.
I am writing a wrapper for PayPal. To do so, my Vb.Net
Assembly must link to the PayPal dlls. As shown in the
code below, some of my methods take parameters
which are types from the PayPal dlls (namespaces).
When I do this, the comments for the respective method
do not show up in the NDoc generated output. I have
verified that the comments do appear in the
<Project>.xml file. So, the issue occurs after that point,
when the XML file is being converted to the set of HTML
files.
To repeat in a less verbose fashion. Methods with
signatures containing types from external dlls do not
have their comments displayed in the NDoc generated
HTML files.
Further Detail:-->
The problem originally showed up when I had a set of
three overloaded constructors. I was getting comments
on the first constructor, but not on the second. The third
was decorated with Friend, so it was not expected to
appear. It was the third overload, the friend, that had the
external type in its signature. If I replaced the external
type with any other type (e.g. String, Object, etc.) the
comments would appear for the first and second
overloads (that is, all would work as expected). After
some fiddling, it became clear that the third (in physical
order) contructor, the friend, would actually appear
second (in physical order) if I made it public. So, it was
the problem with the Friend that was causing the
second constructor (third in HTML output order, but
second in physical order within my source) to fail.
In other words, any overload generated after the overload
with the signature containing the external type would
also not get comments in the HTML (even if the overload
with the external type in its signature was a friend, and
therefore not actually displayed in the HTML).
In the end, I simplified the code to what is shown below.
And, consequently, the issue is the far more simple
problem with signatures of methods containing types
from external dlls. It does not matter if they are
overloads or if they are constructors. Any method, with
any type from any external dll will not have comments
displayed in the HTML.
Sample code is below.
Sample Code With Comments:-->
Imports System.Text
Imports com.paypal.soap.api
''' -----------------------------------------------------------------------------
''' <summary>
''' A wrapper class for buyer addresses.
''' </summary>
''' -----------------------------------------------------------------------------
Public Class Address
''' ----------------------------------------------------------------------------
----
''' Class.Method: Newb
''' <summary>
''' Constructs an Address.
''' </summary>
''' <param name="addr">
''' A PayPal AddressType returned from a call
to a PayPal web service.
''' </param>
''' ----------------------------------------------------------------------------
----
Public Sub Newb(ByVal addr As AddressType)
End Sub
End Class
Logged In: YES
user_id=1329541
I can now make NDoc not work in what seems to be an
inifinite number of situations. I have reviewed the XML file
generated by the latest version of VBCommenter, and it
matches the expected types/signatures in the 'allegedly
missing' summaries, remarks, etc. that NDOC doesn't seem
to be able to find. Furthermore, I can remove classes from my
project, and then other classes miraculously have their NDoc
HTML pages working again. I can change from one data type
to another, and then, like magic, NDoc starts working again.
This is really flaky stuff. I recognize it is free, but,
unfortunately, it is also a DeFacto standard, and I have no
option but to use it. It simply does not function. How do I go
about getting support. I have a client waiting for my
deliverable. My code is complete, and so far, the
documentation effort (dealing solely with NDoc not working for
me) has taken longer than the actual code. I really need
some help. I can provide files that will not work. they are
simple files, with simple comments, and they just don't work.
Where do I go from here.
Logged In: YES
user_id=1329541
Alright, seems there were two issues. First, I was originally
using an old version of VBCommenter - which caused my
original issue. That was fixed by downloading the latest
version of VBCommenter. Then, the other problem was all
my fault. I had 120 br tags. For 118 of them I had created
the correct br-slash tag. For two of them, I had only the open
br tag. For some reason this did not make the XML invalid
and it also caused no errors in the NDoc program. In fact,
with the two unclosed br tags I was still able to open the XML
file in IE and VS.NET without any complaint. I don't
understand why there were no errors reported, but all is
working so - my apologies for calling the product flaky.