Prev: Trouble with initialization vector (IV) for AES
Next: Visual Studio 2010 IDE Position
From: Robert on 22 Jun 2010 06:06
Hi, I am wanting to automatically generate my documentation from my C# code
comments. Specifically I am wanting to generate examples that look like this

http://msdn.microsoft.com/en-us/library/ch45axte.aspx

where code examples are shown for VB.NET, C#. C++, F# and JScript

How do you do this and can you do this with VS2010 Pro. I have searched and
cannot find a website telling me how to do this. I would prefer to include a
C# example in my source code comments and have the code generation tool
generate from this the examples in VB.Net, C++, F# and JScript examples
automatically.

Is this a technology that is available and do you C# developers use it. What
tools would you recommend

Thank you
Robert



From: Peter Duniho on 22 Jun 2010 11:11
Robert wrote:
> Hi, I am wanting to automatically generate my documentation from my C# code
> comments. Specifically I am wanting to generate examples that look like this
>
> http://msdn.microsoft.com/en-us/library/ch45axte.aspx
>
> where code examples are shown for VB.NET, C#. C++, F# and JScript

Do your comments already include code examples? If not, then you can't
produce a web page with code examples from your comments.

> How do you do this and can you do this with VS2010 Pro. I have searched and
> cannot find a website telling me how to do this. I would prefer to include a
> C# example in my source code comments and have the code generation tool
> generate from this the examples in VB.Net, C++, F# and JScript examples
> automatically.

The pages on MSDN are the result of a lot of different sources of
information, starting with but certainly not limited to the data emitted
when you use XML comments in your code.

There's no reason you couldn't embed code examples in your XML comments.
Microsoft already defines/recommends <example> and <code> XML elements
for use in XML comments, and the XML comment parsing in the compiler
will accept any valid XML in the comment, so you could easily include an
attribute on the <code> element to indicate what language it's for.

It seems safe to assume Microsoft is already using those XML elements
for their own online documentation.

But if you want a web page that then presents that information to the
user, you need to write that as well. I'm not aware of any
Microsoft-supported API that will take the XML comment information
output from the compiler and then turn that into documentation pages for
your program that look like those found on MSDN.

On the other hand, it's worth noting that the help system delivered with
VS2010 is based on a common-platform HTTP server mechanism that allows
for new documentation sections to be installed. AFAIK, Microsoft hasn't
published the specification for how that all works, but if you can
figure out the details, then you can just hook into that. Then at least
you don't have to reimplement all the Javascript and server-side
filtering that goes into the MSDN web page presentations (whether it's
the "Classic", "Lightweight", or "Script Free" views that you want).

And of course, just because I'm not aware of a published specification
doesn't mean that one doesn't exist. So you might try to Google/Bing
around for that.

Pete
From: Anja L�nge on 22 Jun 2010 14:39
Robert wrote:
> Hi, I am wanting to automatically generate my documentation from my
> C# code comments. Specifically I am wanting to generate examples that
> look like this
>
> http://msdn.microsoft.com/en-us/library/ch45axte.aspx
>
> where code examples are shown for VB.NET, C#. C++, F# and JScript

Take a look at

[Sandcastle - Documentation Compiler for Managed Class]
http://sandcastle.codeplex.com/

and the GUI
[Sandcastle Help File Builder]
http://shfb.codeplex.com/

Sandcastle uses reflection to find types and members in the assemblies and
looks for them in the xml-output of your VS project to build the
documentation.

I read an article that CruisControl.NET can be scripted to do this during
normal compilation, but I never checked this.

HTH
Anja


From: Robert on 22 Jun 2010 15:09
Hello Peter

> Do your comments already include code examples?

Yes, but only for C#. I want the autohelp generation tool to automatically
generate the example help for other languages from my C# like in the URL. It
seems unreasonable that I should have to generate it for all the languages
when automated conversion seems like something like the help tool should do.

Do you think Microsoft handcraft the examples in their online help for all
languages by hand. I don't think they do. The reason I write this is that
most of the MSDN examples they had were C# and VB.Net and C++. Then overnight
a lot of F# examples appeared. It would have taken them quite a while to
retrospectively do this so I expect they just ran a tool on their code and
had their autogenerated help updated. I guess what I am wanting is to
generate C# example code in my source code and have the C++ and F# example
code autoconverted. At the moment I don't have C++ and F# skills but people
that use my API might have so I want my example usage in those languages too.

I hope this makes sense and thank you for your answer.

Robert W


"Peter Duniho" wrote:

> Robert wrote:
> > Hi, I am wanting to automatically generate my documentation from my C# code
> > comments. Specifically I am wanting to generate examples that look like this
> >
> > http://msdn.microsoft.com/en-us/library/ch45axte.aspx
> >
> > where code examples are shown for VB.NET, C#. C++, F# and JScript
>
> Do your comments already include code examples? If not, then you can't
> produce a web page with code examples from your comments.
>
> > How do you do this and can you do this with VS2010 Pro. I have searched and
> > cannot find a website telling me how to do this. I would prefer to include a
> > C# example in my source code comments and have the code generation tool
> > generate from this the examples in VB.Net, C++, F# and JScript examples
> > automatically.
>
> The pages on MSDN are the result of a lot of different sources of
> information, starting with but certainly not limited to the data emitted
> when you use XML comments in your code.
>
> There's no reason you couldn't embed code examples in your XML comments.
> Microsoft already defines/recommends <example> and <code> XML elements
> for use in XML comments, and the XML comment parsing in the compiler
> will accept any valid XML in the comment, so you could easily include an
> attribute on the <code> element to indicate what language it's for.
>
> It seems safe to assume Microsoft is already using those XML elements
> for their own online documentation.
>
> But if you want a web page that then presents that information to the
> user, you need to write that as well. I'm not aware of any
> Microsoft-supported API that will take the XML comment information
> output from the compiler and then turn that into documentation pages for
> your program that look like those found on MSDN.
>
> On the other hand, it's worth noting that the help system delivered with
> VS2010 is based on a common-platform HTTP server mechanism that allows
> for new documentation sections to be installed. AFAIK, Microsoft hasn't
> published the specification for how that all works, but if you can
> figure out the details, then you can just hook into that. Then at least
> you don't have to reimplement all the Javascript and server-side
> filtering that goes into the MSDN web page presentations (whether it's
> the "Classic", "Lightweight", or "Script Free" views that you want).
>
> And of course, just because I'm not aware of a published specification
> doesn't mean that one doesn't exist. So you might try to Google/Bing
> around for that.
>
> Pete
> .
>
From: Peter Duniho on 23 Jun 2010 00:18
Robert wrote:
> Hello Peter
>
>> Do your comments already include code examples?
>
> Yes, but only for C#. I want the autohelp generation tool to automatically
> generate the example help for other languages from my C# like in the URL. It
> seems unreasonable that I should have to generate it for all the languages
> when automated conversion seems like something like the help tool should do.

Automated conversion is actually not as trivial as one might think.
There is certainly a significant overlap between the various languages,
but even C# and VB.NET, which are very similar, have some specific
idioms and language techniques that preclude 100% automated conversion,
and F# is a very different paradigm altogether.

> Do you think Microsoft handcraft the examples in their online help for all
> languages by hand. I don't think they do.

Given that examples exist in various combinations, where some doc pages
have examples in all languages, others in just a few or only two, I see
no reason to assume any particular approach to creating the examples was
used, whether by hand, some automation, or all automation. We are not
in a position to deduce that information.

> The reason I write this is that
> most of the MSDN examples they had were C# and VB.Net and C++. Then overnight
> a lot of F# examples appeared.

You have no idea how long they were working on the examples. It's
entirely possible that the documentation update had been under progress
for months or even years. Then the entire result was shown to you all
at once. There's no way for you or me from the outside to know what
kind of effort was involved.

I wouldn't be surprised if they'd used some automation, but it would be
foolish for them to rely on that automation completely. A lot of time
could be saved with an automated tool, but a real human being would
still need to go through an ensure the results were correct.

In any case, I'm positive that the code examples are not auto-generated
by the help system itself. Assuming there's automation involved at all,
it would be a production tool to create the database the help system
uses, not a real-time web server tool.

Beyond all that, the techniques that Microsoft used to provide code
examples for MSDN aren't really all that relevant to your question,
since AFAIK Microsoft isn't making whatever automation they may or may
not have used available to us to use.

You can debate _how_ Microsoft accomplished it until the cows come home,
that won't make automation any more available to you than it is right now.

Pete
 |  Next  |  Last
Pages: 1 2
Prev: Trouble with initialization vector (IV) for AES
Next: Visual Studio 2010 IDE Position