Home | Contact Us | FAQ | Search & Site Map | Link to Us
Sign In | Join | Other 45 Sites in Network
HomeAnnouncementsFree MagazinesWhite PapersSubmit Content
Discussion GroupsASP.NETWindows FormsLanguages.NET FrameworkVisual Studio.NET
Articles.NET FrameworkASP.NETToolsWindows Forms
.NET DirectoryOpen Source ProjectsUser GroupsWeb Resources
Related Topics
Visual Basic 6SQL ServerMS AccessOther DB ProductsMS Server ProductsMore Topics ...

.NET Forum / Languages / C# / March 2008

Tip: Looking for answers? Try searching our database.

Creating a list of TODO's

Thread view: 
Enable EMail Alerts  Start New Thread
Thread rating: 
K Viltersten - 23 Mar 2008 17:36 GMT
Is there a facility in VS allowing the
programmer to find and list all "TODO"
locations in the code?

In C++ i had this "\todo text" which
resulted in a list of things todo as
a separate HTML file upon run...

--
Regards
Konrad Viltersten
--------------------------------
sleep    - a substitute for coffee for the poor
ambition - lack of sense to be lazy
Alberto Poblacion - 23 Mar 2008 18:39 GMT
> Is there a facility in VS allowing the
> programmer to find and list all "TODO"
> locations in the code?

  In the "View" menu, select "Task List", and then in the Task List window,
use the dropdown to select "Comments". This should bring up a list of al the
//TODO comments. Double-clicking in any of them will jump to the location in
code where it is written.
Jeroen Mostert - 23 Mar 2008 18:45 GMT
> Is there a facility in VS allowing the
> programmer to find and list all "TODO"
> locations in the code?

Well, first of all, there's the Task List (View -> Task List). For comments
it only works on the currently opened file, but it works across files for
shortcuts (Edit -> Bookmarks -> Add Task List Shortcut). This requires
manual maintenance, though.

Then there's the obvious "Find in Files" (Ctrl+Shift+F). You can copy+paste
the output of that.

> In C++ i had this "\todo text" which
> resulted in a list of things todo as
> a separate HTML file upon run...

Automatic generation, on the other hand, is another matter. If it's
important that this is done at every build, you can use a post-build event
to hook up a batch file that will search all files (a simple FINDSTR should
do). VS doesn't really have a facility for this, unless you count XML
comments (which still require a separate doc generator).

Signature

J.

K Viltersten - 23 Mar 2008 22:02 GMT
>> In C++ i had this "\todo text" which
>> resulted in a list of things todo as
[quoted text clipped - 3 lines]
> unless you count XML comments (which still
> require a separate doc generator).

I've been hearing "XML comments" mentioned
a number of times. I'd like to get your
opinion on this.

1. Is there a standard of commenting using
XML or is it rather "every one does as one
pleases"? Several competing standards?

2. Is it a good idea to go in depth with
the XML commenting and adapt it seriously or
is it rather sparely used?

Thanks for the answers, by the way.

--
Regards
Konrad Viltersten
--------------------------------
sleep    - a substitute for coffee for the poor
ambition - lack of sense to be lazy
Jeroen Mostert - 23 Mar 2008 22:38 GMT
>>> In C++ i had this "\todo text" which
>>> resulted in a list of things todo as
[quoted text clipped - 9 lines]
> XML or is it rather "every one does as one
> pleases"? Several competing standards?

Bit of both, actually. There's a baseline set of tags used by everyone and
documented in the MSDN, some of which actually come with generated
Intellisense (like <summary>) and compiler support (like <param> and
<seealso>, where the compiler will verify that you're referring to existing
parameters/types).

Then there are minor extensions like (<langword>) that are widely supported
but not exactly standardized, and finally it's always possible to just
invent your own tags for specific purposes -- like <pre> and <post> if you
want to annotate your source with pre- and postconditions.

Almost all tools out there that process XML documentation are flexible
enough to allow you to specify your own tags and how they should be
processed, so there's little competition going on, really.

> 2. Is it a good idea to go in depth with the XML commenting and adapt it
> seriously or is it rather sparely used?

Depends on what you're trying to achieve.

First of all, XML comments are just a good idea if you're writing a library,
or in general any sort of code that's going to be used by other people,
since it allows you to

- Provide good Intellisense support: see the use and purpose of a method or
enum value as you're typing;
- Add special usage notes or semantic restrictions that aren't expressible
in code;
- Specify what argument values a method accepts, the exceptions it can
throw, and under what circumstances it throws them.

And this is in addition to the standard <summary> documentation that allows
you to explain what things do in the first place. Your documentation may
actually be more extensive than what XML comments can provide (tutorials,
samples, broad overviews, etc.) but XML comments should definitely be a part.

Whether you should be creative in adding your own tags, that's another
matter. The baseline set of tags is actually pretty extensive, and there
aren't that many cases where you'd really want to add your own semantic
information (the pre- and postconditions I mentioned would be one, if you do
programming by contract). However, XML comments are flexible enough that you
can actually do this without much fuss -- if you often need to cooperate
with other developers on code that's incomplete, for example, <todo> might
come in handy.

If you just need to search on TODOs without the rest of the documentation,
on the other hand, XML comments aren't any more handy than regular comments,
unless you write your own processing tools.

Signature

J.

Lasse Vågsæther Karlsen - 24 Mar 2008 12:16 GMT
<snip>
> Then there are minor extensions like (<langword>) that are widely
> supported but not exactly standardized, and finally it's always possible
[quoted text clipped - 4 lines]
> enough to allow you to specify your own tags and how they should be
> processed, so there's little competition going on, really.

Just need to ask... are there that many tools? The two I know of are
NDoc and Sandcastle, and NDoc is dead, and Sandcastle ought to be, are
there any others?

Signature

Lasse Vågsæther Karlsen
mailto:lasse@vkarlsen.no
http://presentationmode.blogspot.com/
PGP KeyID: 0xBCDEA2E3

Jeroen Mostert - 24 Mar 2008 13:05 GMT
> <snip>
>> Then there are minor extensions like (<langword>) that are widely
[quoted text clipped - 9 lines]
> Just need to ask... are there that many tools? The two I know of are
> NDoc and Sandcastle, and NDoc is dead, and Sandcastle ought to be,

Oh, come on. It's still in the early stages. It's slow and ponderous, but it
does get the job done.

You can still use the alpha build of NDoc for .NET 2.0 if you're so
inclined, which is at least faster.

> are there any others?

Serious projects? No. The rest is all incidental stuff (and most of it died
when NDoc came around). Visual Studio .NET actually had its own rudimentary
documentation builder (Tools -> Build Comment Web Pages), but this feature
wasn't carried forward.

Signature

J.

BobF - 24 Mar 2008 14:20 GMT
Doxygen?

> <snip>
>> Then there are minor extensions like (<langword>) that are widely
[quoted text clipped - 9 lines]
> and Sandcastle, and NDoc is dead, and Sandcastle ought to be, are there
> any others?
K Viltersten - 24 Mar 2008 14:43 GMT
> Doxygen?

I'm no expert on Doxygen but when we
used it for our C++ project, the
comments needed to be like:

 /** A method that is SOOO cool.
     \param input parameter in
   */

and that it wasn't possible to use
XML comment system at all. Is it
still true?

--
Regards
Konrad Viltersten
--------------------------------
sleep    - a substitute for coffee for the poor
ambition - lack of sense to be lazy
K Viltersten - 24 Mar 2008 14:55 GMT
> Doxygen?

Also, have the issues with partial
classes and other minor problems
been resolved?

--
Regards
Konrad Viltersten
--------------------------------
sleep    - a substitute for coffee for the poor
ambition - lack of sense to be lazy

Rate this thread:







Free Magazines

Get these publications absolutely FREE for up to 12 months. There are no hidden fees and no obligation. Simply choose a title, complete the application form and submit it. Read more ...

Oracle MagazineNetwork ComputingComputer WorldBio-IT WorldeWeekInformation WeekInfosecurity
 
Sign In
Join
My Latest Posts
My Monitored Threads
My Blog
My Photo Gallery
My Profile
My Homepage

Start New Thread
Enable EMail Alerts
Rate this Thread



©2008 Advenet LLC   Privacy Policy - Terms of Use
This website includes both content owned or controlled by Advenet as well as content owned or controlled by third parties.