Ndoc: tags inside the methods

[julien]

Hello,
I posted this question on the NDoc-user mailing list, but it looks like
a dead list (no messages for 10 days!).

I'd like to use NDoc tags or custom tags inside methods like:
void Mymethod() {
.....
<mytag>...</mytag>
....
}

NDoc generates documentation for tags outside the methods, but not for
tags inside. I didn't see any documenter that would allow me to do that.

Any idea?

Thanks
Julien

[Christoph Nahr]

On Fri, 29 Apr 2005 23:45:33 -0400, julien <ju****@sobrier.net> wrote:

Hello,
I posted this question on the NDoc-user mailing list, but it looks like
a dead list (no messages for 10 days!).
Try posting to the SourceForge forums for NDoc, they're always
monitored by the developers.
I'd like to use NDoc tags or custom tags inside methods like:
void Mymethod() {
....
<mytag>...</mytag>
...
}

NDoc generates documentation for tags outside the methods, but not for
tags inside. I didn't see any documenter that would allow me to do that.

That's not possible. NDoc only processes the XML files created by the
C# compiler, and the C# compiler only extracts the XML comments that
are specified by the C# standard -- at the top of methods or classes.

You could write your own source code processor that mixes those inline
comments into the compiler-generated XML files, though...
--
http://www.kynosarges.de

[Gelios]

julien wrote:

Hello,
I posted this question on the NDoc-user mailing list, but it looks like
a dead list (no messages for 10 days!).

I'd like to use NDoc tags or custom tags inside methods like:
void Mymethod() {
.....
<mytag>...</mytag>
....
}

NDoc generates documentation for tags outside the methods, but not for
tags inside. I didn't see any documenter that would allow me to do that.

Any idea?

Thanks
Julien

Try to use custom attributes.

[Christoph Nahr]

On Sat, 30 Apr 2005 14:08:05 +0400, Gelios <ge****@rbcmail.ru> wrote:

Try to use custom attributes.

Are you sure this reply has anything to do with the question?
--
http://www.kynosarges.de

[Gelios]

Christoph Nahr wrote:

On Sat, 30 Apr 2005 14:08:05 +0400, Gelios <ge****@rbcmail.ru> wrote:

Try to use custom attributes.

Are you sure this reply has anything to do with the question?

I just want to show direction of future investigations.
Guess explaining custom attributes will take a lot of pages and I think it will be better to read some book.
OK, probably I wasn't right.
About custom attributes author of first question can read in Wrox Press - Professional C#, 3rd Edition book.
I even ready to send e-book, but it's size about 10 Mb in zip.

[Jon Skeet [C# MVP]]

Gelios <ge****@rbcmail.ru> wrote:

Are you sure this reply has anything to do with the question?

I just want to show direction of future investigations.

I don't think investigating attibutes would help the OP at all though -
it's separate from doc comments, which basically can't appear (or at
least are ignored) within methods.

One potential direction of future investigation would be the Mono C#
compiler, which could be modified to make use of doc comments within
methods.

--
Jon Skeet - <sk***@pobox.com>
http://www.pobox.com/~skeet
If replying to the group, please do not mail me too

[julien]

Christoph Nahr a écrit :

I'd like to use NDoc tags or custom tags inside methods like:
void Mymethod() {
....
<mytag>...</mytag>
...
}

NDoc generates documentation for tags outside the methods, but not for
tags inside. I didn't see any documenter that would allow me to do that.

That's not possible. NDoc only processes the XML files created by the
C# compiler, and the C# compiler only extracts the XML comments that
are specified by the C# standard -- at the top of methods or classes.

You could write your own source code processor that mixes those inline
comments into the compiler-generated XML files, though...

Thank you for the information.

[Daniel O'Connell [C# MVP]]

"julien" <ju****@sobrier.net> wrote in message
news:42***********************@news.free.fr...

Hello,
I posted this question on the NDoc-user mailing list, but it looks like a
dead list (no messages for 10 days!).

I'd like to use NDoc tags or custom tags inside methods like:
void Mymethod() {
....
<mytag>...</mytag>
...
}

While others have already pointed out the compiler doesn't support this,
could I ask what you are trying to achieve? What particular code constructs
would you want to document?
Thanks
Julien

[Dave]

Sounds interesting, but I'd like to play Devil's Advocate for a moment...

What good is external documentation on lines of code that aren't also present? I mean that if you document your actual code, don't
you need to look at the code for the documentation to make any sense?

So my next question is, will this "inline-documenter" pull out code snippets to? Personally, I'd rather just look at the source.
Just my opinion, although nobody asked ;)

--
Dave Sexton
dave@www..jwaonline..com
-----------------------------------------------------------------------
"Jon Skeet [C# MVP]" <sk***@pobox.com> wrote in message news:MP************************@msnews.microsoft.c om...

Gelios <ge****@rbcmail.ru> wrote:

> Are you sure this reply has anything to do with the question?

I just want to show direction of future investigations.

I don't think investigating attibutes would help the OP at all though -
it's separate from doc comments, which basically can't appear (or at
least are ignored) within methods.

One potential direction of future investigation would be the Mono C#
compiler, which could be modified to make use of doc comments within
methods.

--
Jon Skeet - <sk***@pobox.com>
http://www.pobox.com/~skeet
If replying to the group, please do not mail me too

[Christoph Nahr]

On Sun, 1 May 2005 00:05:07 -0400, "Dave"
<NO*********@dotcomdatasolutions.com> wrote:

Sounds interesting, but I'd like to play Devil's Advocate for a moment...

What good is external documentation on lines of code that aren't also present? I mean that if you document your actual code, don't
you need to look at the code for the documentation to make any sense?
Sometimes a method may exhibit strange behavior or usage restrictions
that are due to some old bug in Windows 2000 or whatever. It would
make sense to document such special behavior right next to the code
where it's implemented, so you don't accidentally forget to modify the
comments when changing the code.
So my next question is, will this "inline-documenter" pull out code snippets to? Personally, I'd rather just look at the source.
Just my opinion, although nobody asked ;)

Actually, this idea already exists -- it's called "literary
programming". You write a paragraph or two of explanations for every
few lines of code. The whole thing is run through a typesetter (TeX)
for printable documentation with code snippets, or through a
preprocessor that strips the explanations to get source code.

Has never caught on outside the academic community, though...
--
http://www.kynosarges.de

[Dave]

Pulling out inline-comments w/code snippets still seems strange to me though. When I write code, and add inline comments, the
comments usually have something to do with the context of the code. i.e., It wouldn't make sense to say, pull out the comment and
the line right after it.

So how could any "TeX" possibly know what code is required for any particular comment?

In the case for handling "strange behavior" or "bug fixes" I believe the same is true. This would be something in, say, the
"remarks" section on a method. Inline comments would be useful for identifying the exact block or line of code that applies to the
remarks, but would it really be useful if extracted?
--
Dave Sexton
dave@www..jwaonline..com
-----------------------------------------------------------------------
"Christoph Nahr" <ch************@kynosarges.de> wrote in message news:a3********************************@4ax.com...

On Sun, 1 May 2005 00:05:07 -0400, "Dave"
<NO*********@dotcomdatasolutions.com> wrote:

Sounds interesting, but I'd like to play Devil's Advocate for a moment...

What good is external documentation on lines of code that aren't also present? I mean that if you document your actual code,
don't
you need to look at the code for the documentation to make any sense?

Sometimes a method may exhibit strange behavior or usage restrictions
that are due to some old bug in Windows 2000 or whatever. It would
make sense to document such special behavior right next to the code
where it's implemented, so you don't accidentally forget to modify the
comments when changing the code.

So my next question is, will this "inline-documenter" pull out code snippets to? Personally, I'd rather just look at the source.
Just my opinion, although nobody asked ;)

Actually, this idea already exists -- it's called "literary
programming". You write a paragraph or two of explanations for every
few lines of code. The whole thing is run through a typesetter (TeX)
for printable documentation with code snippets, or through a
preprocessor that strips the explanations to get source code.

Has never caught on outside the academic community, though...
--
http://www.kynosarges.de

[Christoph Nahr]

On Sun, 1 May 2005 08:50:09 -0400, "Dave"
<NO*********@dotcomdatasolutions.com> wrote:

So how could any "TeX" possibly know what code is required for any particular comment?
TeX is the name of a popular open-source typesetting system. It
doesn't know anything -- the point of literate programming is to write
code & documentation together, in a single text file (per class or
whatever), but marked up differently so that extraction is automatic.

Google on "literate programming" (not "literary" -- sorry, that was
misspelled in my previous post). Or just have a look at the examples
at http://www.literateprogramming.com/.
In the case for handling "strange behavior" or "bug fixes" I believe the same is true. This would be something in, say, the
"remarks" section on a method. Inline comments would be useful for identifying the exact block or line of code that applies to the
remarks, but would it really be useful if extracted?

My point with this example was that the "remarks" section is removed
from the actual lines of code they are commenting. With inline
comments that can be extracted, you could have code and comments in
close vicinity but still format the comments nicely for documentation.
--
http://www.kynosarges.de