documentation

[J Ames]

My team has recently been moved into the Microsoft space from the Java
space. For the most part we are really enjoying the VS.NET 2005
environment, and have had little problem picking up C# (and VB.NET too since
almost every developer these days has gone thru a VB phase). The problem we
have found is that there apparently is no equivalent to javadoc in VS.NET.
We found where you can use XML based comments and create a XML documentation
file with your build, but there nothing to actually create HTML
documentation akin to javadoc. I did some research on the 'net and saw that
it was previously available prior to VS.NET 2005, and until recently there
was a open source option for VB called NDoc. Now it looks like there's some
new deal from Microsoft called Sandcastle, but getting output from it takes
about 3 days of hideous command line juggling. Kind of ridiculous to have a
world class IDE and then have to revert back to 1970's style Unix black
screens to get your documentation created.

So, do I have the story correct, or is there something out there that I can
give to my team before they roll over laughing?

Thanks
J

 

[Alan Pretre]

We found where you can use XML based comments and create a XML
documentation file with your build, but there nothing to actually create
HTML documentation akin to javadoc. I did some research on the 'net and
saw that it was previously available prior to VS.NET 2005, and until
recently there was a open source option for VB called NDoc. Now it looks
like there's some new deal from Microsoft called Sandcastle, but getting
output from it takes about 3 days of hideous command line juggling.

The NDoc project has ceased for the time being, though some have expressed
an interest in taking over admin of it.

It seems SandCastle is the way to go at this point. Yes, the command line
is crude, but some have provided batch files. Follow this blog, SandCastle
will improve with time, will probably integrate with VS.NET.

http://blogs.msdn.com/sandcastle/


If you don't mind spending money, Innovasys has a product, looks nice.

http://www.innovasys.com/products/dx5/overview.asp


-- Alan

 

[Kevin Spencer]

The VS.Net XML Comments create an XML document. There is an excellent reason
that an XML document is created rather than the previous HTML document. You
can use XSL to transform an XML document into any document format. You can
not do this with HTML.

The answer is, therefore, to use XSL to transform the XML to any format you
like. Here is an example of an HTML documentation system I created for our
in-house software. It uses the same XSL to do a transform on any code we
write:

http://www.dynamicsystems.com/weatherservices/documentation/DsiGlobal.Geography.htm

--
HTH,

Kevin Spencer
Microsoft MVP
Chicken Salad Surgery

Expect the unaccepted.

 

[Jani Järvinen [MVP]]

Hello,

Now it looks like there's some new deal from Microsoft called Sandcastle,
but getting output from it takes about 3 days of hideous command line
juggling.

Yes, Sandcastle is probably going to be The Way to build automatic
documentation in the future, but it is not yet ready for primetime just yet.
As others have mentioned, at present you need to write XSL transforms to get
HTML from the compiler-generated XML files. You could use an XSLT editor to
help you there, though.

There's also an older MSDN Magazine article that might help you here:

http://msdn.microsoft.com/msdnmag/issues/02/06/XMLC/

And for reference, Borland's Developer Studio (aka Delphi) comes with a
sample application named XMLDoc. However, it is a combination of Python and
Java code (!), which means it isn't easy to use, either.

http://bdn.borland.com/article/32770

--
Regards,

Mr. Jani Järvinen
C# MVP
Helsinki, Finland
(e-mail address removed)
http://www.saunalahti.fi/janij/

 

[Jani Järvinen [MVP]]

Kevin,

Here is an example of an HTML documentation system I created for our
in-house software.

Good stuff! I wish Visual Studio (or the SDK pack for that matter) would
come with at least a simple XSLT file that people could use.

--
Regards,

Mr. Jani Järvinen
C# MVP
Helsinki, Finland
(e-mail address removed)
http://www.saunalahti.fi/janij/

 

[Kevin Spencer]

Hi Jani,

Actually, they do:

http://msdn.microsoft.com/msdnmag/issues/02/06/XMLC/
http://msdn.microsoft.com/library/d...en-us/dv_vstechart/html/vstchexpvsnetlab2.asp

--
HTH,

Kevin Spencer
Microsoft MVP
Chicken Salad Surgery

Expect the unaccepted.

 

[Jani Järvinen [MVP]]

Hi Kevin,

Actually, they do:

http://msdn.microsoft.com/msdnmag/issues/02/06/XMLC/
http://msdn.microsoft.com/library/d...en-us/dv_vstechart/html/vstchexpvsnetlab2.asp

Yes, I'm aware of these (see my other post to the original poster), but not
that many people aren't.

I mean, why not include one or two XSLT files with Visual Studio that would
help users generate decent HTML documentation out of the box?

--
Regards,

Mr. Jani Järvinen
C# MVP
Helsinki, Finland
(e-mail address removed)
http://www.saunalahti.fi/janij/

 

[Kevin Spencer]

Hi Jani,

That might not be a bad idea. Perhaps even a Template that the developer can
use as a start?

--
HTH,

Kevin Spencer
Microsoft MVP
Chicken Salad Surgery

Accept the Unexpected.

 

[Jani Järvinen [MVP]]

Hello Kevin,

That might not be a bad idea. Perhaps even a Template that the developer
can use as a start?

Yes, that would be great. What I would like to see is that when the
developer goes to project properties in Visual Studio and selects the "XML
documentation file" option under the Build tab, at the same time s/he could
select the XSLT template (or a set of such) that s/he would like to use to
build HTML documentation from the compiler-generated XML file.

I guess eventually Sandcastle will be integrated into Visual Studio, but do
you think in the mean time we could file a request about this for Microsoft?

--
Regards,

Mr. Jani Järvinen
C# MVP
Helsinki, Finland
(e-mail address removed)
http://www.saunalahti.fi/janij/

 

[Kevin Spencer]

Well, Jani, they do read these newsgroups!

--
HTH,

Kevin Spencer
Microsoft MVP
Chicken Salad Surgery

Accept the Unexpected.

 

[Jani Järvinen [MVP]]

Hello!

Well, Jani, they do read these newsgroups!

Sure Kevin, they do. But using forums/newsgroups for product suggestions is
like fishing with a hook and line in a pond; you never know what and when
you will get.

--
Regards,

Mr. Jani Järvinen
C# MVP
Helsinki, Finland
(e-mail address removed)
http://www.saunalahti.fi/janij/

 

[Kevin Spencer]

I suppose they have a "Wish List" somewhere, but I don't know where it is
offhand. In any case, using it may increase the probability of someone
reading it, but doesn't guarantee that it will be implemented. If you like,
you can try to find it.

--
HTH,

Kevin Spencer
Microsoft MVP
Chicken Salad Surgery

Accept the Unexpected.

 

[Jani Järvinen [MVP]]

Hello again,

I suppose they have a "Wish List" somewhere, but I don't know where it is
offhand.

The system used to be the Product Feedback Center (aka "Ladybug"), but this
has since then moved to Connect.

That is, to give feedback, report bugs and make suggestions or wishes for
Visual Studio or .NET Framework, one has to go here:

http://connect.microsoft.com/VisualStudio

I checked this site, and found that there are already two suggestions for
XSLT files that we've been discussing (IDs 105723 and 114523). Although both
have the status of "Closed", the former has been marked as being
"Postponed". So Microsoft is aware of our (mine at least) wish, and we'll
see what the "Orcas" release of Visual Studio will bring.

--
Regards,

Mr. Jani Järvinen
C# MVP
Helsinki, Finland
(e-mail address removed)
http://www.saunalahti.fi/janij/