🔒 Locked

Creating Documentation

Started by thk123 Apr 5, 2009 at 3:58 PM 11 replies 2k views

Original Post

Apr 5, 2009 at 3:58 PM

I am working on a C#/XNA RTS and my code has now reached the point where it is becoming quite large (for me, at least). What I was looking for is a system which allows me to document my programming. I want a simmilar thing to what the MSDN Libary where you can expand each object and see its memebers, functions etc. Obviously I could do something simmilar in a word processing aplication, but if such a system exists (free) that allows me to quickly create such a thing, I would love to use it as it would allow me to quickly find the revlevant documentation. I'm not sure if this explanation is very clear, thanks for any replies.

SiCrane

Mod

473

SiCrane

Apr 5, 2009 at 4:00 PM

You might want to try an automatic source code documentation generator like Doxygen or Natural Docs.

thk123

Author

thk123

Apr 5, 2009 at 4:18 PM

That is exactly what I was looking for, thank you so much! :D

ChaosEngine

784

ChaosEngine

Apr 5, 2009 at 10:36 PM

To generate the documentation, you could also try Sandcastle. It will generate docs that look almost identical to msdn.

Useful little util in C# is Ghost Doc to generate the comments. It's not perfect, but it certainly does a good job of generating the boilerplate comments. Only problem is I don't think it works with the express editions (they don't allow add-ins IIRC).

To give you an example, the method

public bool WriteToDB(string connectionString, List<int> data)

generates the following xml docs

        /// <summary>        /// Writes to DB.        /// </summary>        /// <param name="connectionString">The connection string.</param>        /// <param name="data">The data.</param>        /// <returns></returns>        public bool WriteToDB(string connectionString, List<int> data)

One of the really nice things about it is that it will copy the base comments for overridden functions.

sardak

Apr 6, 2009 at 3:37 AM

Quote:

Original post by ChaosEngine

        /// <summary>        /// Writes to DB.        /// </summary>        /// <param name="connectionString">The connection string.</param>        /// <param name="data">The data.</param>        /// <returns></returns>        public bool WriteToDB(string connectionString, List<int> data)

Maybe it's just me, but I really dislike the way most of these documenting systems clutter the code with giant comment blocks like that. It makes it hard to see the actual code through all the comments.

That said, I'm currently using NaturalDocs, which isn't too bad, because you can compress the comment block's size down to just a couple lines for self-explanatory functions and variables. The actual output isn't terrible, but it leaves a lot to be desired. Then again, I'm not going to pull myself away from coding long enough to write real documentation, either.

ChaosEngine

784

ChaosEngine

Apr 6, 2009 at 4:00 PM

Quote:
Original post by sardak
Quote:
Original post by ChaosEngine
        /// <summary>        /// Writes to DB.        /// </summary>        /// <param name="connectionString">The connection string.</param>        /// <param name="data">The data.</param>        /// <returns></returns>        public bool WriteToDB(string connectionString, List<int> data)
Maybe it's just me, but I really dislike the way most of these documenting systems clutter the code with giant comment blocks like that. It makes it hard to see the actual code through all the comments.

1: That is the C# xml documentation syntax. It's the "official" way of documenting C#.

2: In any decent IDE, comments are formatted differently to code. If you're still writing code in notepad, you're wasting your time.

3: Picking a file totally at random, the file is 220 lines long (a short one) and roughly 50 lines are comments. I think that's a small price to pay for automatic documentation.

Ezbez

154

Ezbez

Apr 6, 2009 at 4:09 PM

Also, Visual C# 2005 lets you collapse the comments when they're not needed. That way, all those comments take up only one line per function, class, etc.

SiCrane

Mod

473

SiCrane

Apr 6, 2009 at 4:23 PM

Quote:
Original post by ChaosEngine
3: Picking a file totally at random, the file is 220 lines long (a short one) and roughly 50 lines are comments. I think that's a small price to pay for automatic documentation.

That's a flawed argument. The situation isn't Sandcastle or nothing, it's Sandcastle versus other existing automatic source documentation systems, some of which, like Natural Docs, have a lower comment versus code ratio.

sardak

Apr 6, 2009 at 11:36 PM

Quote:
Original post by SiCrane
Quote:
Original post by ChaosEngine
3: Picking a file totally at random, the file is 220 lines long (a short one) and roughly 50 lines are comments. I think that's a small price to pay for automatic documentation.

That's a flawed argument. The situation isn't Sandcastle or nothing, it's Sandcastle versus other existing automatic source documentation systems, some of which, like Natural Docs, have a lower comment versus code ratio.

Also, I just tried this hypothetical experiment. One of the headers in a project I'm actively working on is 221 lines long (close enough to the quoted size). 124 lines of that are documentation comments, not even regular comments in a few of the inline/template functions. Also, not every function/variable is even documented, since some of them are fairly trivial and obvious by their names.

It's a pain to read through, even with them collapsed.

Mike.Popoloski

197

Mike.Popoloski

Apr 6, 2009 at 11:46 PM

The SlimDX team uses embedded doc comments along with Sandcastle to generate its documentation. We use DocProject as a front end for adding articles to Sandcastle.

If you expand the Class Reference section, you'll see that it looks similar to the MSDN documentation, with actual links to MSDN for related subjects. Further, we developed a tool that uses Google Search and custom code comments to match up DirectX reference pages on MSDN to their corresponding types in SlimDX.

phresnel

124

phresnel

Apr 7, 2009 at 7:56 AM

Quote:
Original post by ChaosEngine
2: In any decent IDE, comments are formatted differently to code. If you're still writing code in notepad, you're wasting your time.

Out of curiousity, what exactly do you mean with "formatted differently"? Because, for me, notepad and "IDE editors" both show the same different format:

notepad:

// commentint i = 0;

ide text editor:

// commentint i = 0;

(out of inquisitiveness: there is a plethora of syntax highlighting editors that are not part of any IDE; would you say I am wasting my time if I use one of those?)

Quote:
Original post by ChaosEngine
3: Picking a file totally at random, the file is 220 lines long (a short one) and roughly 50 lines are comments. I think that's a small price to pay for automatic documentation.

If you have to write comments for the documentation, it can't be automatic. I guess you meant semi-automatic. Imho, automatic is what e.g. doxygen would give you if you run it over 'undocumented code'. Which is, btw, in many cases already saturating, if you write code with an eye on the fact that code itself is already a kind of documentation (i.e. write self explaining code, and that could then be inlined in the doxygenized documentation).

[Edited by - phresnel on April 7, 2009 8:56:00 AM]

phresnel

124

phresnel

Apr 7, 2009 at 8:26 AM

I was curious whether C# XML comments are part of the language specification. I hereby neutrally share what I found out:

Quote:
Annex E. Documentation Comments (ECMA-334, p. 487, et seq.)

A conforming C# compiler is not required to check the syntax of documentation comments; such comments are simply ordinary comments. A conforming compiler is permitted to do such checking, however.

[...]

This specification suggests a set of standard tags to be used in documentation comments

[...]

Although developers are free to create their own set of tags, a recommended set is defined in §E.2. Some of the recommended tags have special meanings [...]

Anon Mike

117

Anon Mike

Apr 7, 2009 at 11:15 AM

I personally detest doxygen and similar "automatic documentation generators". In almost every case I've ever seen them used it's ended up being a cop-out where the developer can claim to have documentation, despite the fact that it's so crappy as to be worse than nothing (having nothing at least sets expectations correctly).

There are basically two types of documentation that you need, docs for users (i.e. how to use it), and docs for internal developers (i.e. how it does it). IMHO the former should not be included in the code. It just gets in the way and you are to limited as far as modern expectations go (e.g. active links to related topics).

The latter could concievably be handled by doxygen or it's ilk, but IMHO all the metadata just makes it hard to read for very limited added value.

Topic Locked

This topic has been locked by a moderator. New replies are not allowed.