Ndoc: tags inside the methods

  • Thread starter Thread starter julien
  • Start date Start date
J

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
 
Hello,
I posted this question on the NDoc-user mailing list, but it looks like
a dead list (no messages for 10 days!).
Click to expand...

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.
Click to expand...

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...
 
julien said:
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
Click to expand...

Try to use custom attributes.
 
Christoph said:
Are you sure this reply has anything to do with the question?
Click to expand...
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.
 
I just want to show direction of future investigations.
Click to expand...

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.
 
Christoph Nahr a écrit :
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...
Click to expand...

Thank you for the information.
 
julien said:
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>
...
}
Click to expand...

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?
 
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 ;)
 
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?
Click to expand...

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 ;)
Click to expand...

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...
 
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?
 
So how could any "TeX" possibly know what code is required for any particular comment?
Click to expand...

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?
Click to expand...

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.
 
Back
Top