Inline documentation ... both, blessing and a curse

[stoneCold]

I guess quite everyone in here has already used tools such as Doxygen or JavaDoc to generate API documentation from a piece of source code with inlined documentation comments.
Just recently when I started documenting some of my own source code, which did not have any documentation comment blocks inside it up to this point, I recognised how disturbing these documentation blocks really are when trying to read the actual code that is embedded between them.
You can see this in each software project that uses such tools for documenting its API (e.g. have a look at OgreRoot.h from line 200 on).

Don't understand me wrong, I'm not trying to tell that documentation is bad, hell no. The more documentation an API has got the better, I'm just trying to point out how unpleasing the documentation comment blocks can be to the programmer's eye. It might be not that bad if you just look at a single method, but once you try to have a look at the overall methods of a class or you are searching for a particular method in a file manually, then it becomes a lot worse.

In my case I currently have just small documentation blocks in the named code and they will just grow with time presumably, but I already don't like how this small blocks disrupt the actual code.
To overcome the issue I created a small Visual Studio addin which will just fold in all documentation blocks of the currently active source file.

Have a look at the following screenshot...


left side: a piece of code with some small documentation blocks in it.
right side: the same code after my custom addin has been executed (it just folded all documentation blocks)

As you see at the red markings in the screenshot, you can still see the UI controls that visual studio inserts to indicate the folded documentation blocks.
In my case I just made their color nearly the same as the usual text background color, so that they are nearly invisible and aren't disturbing to the eye.

Still, those UI controls that visual studio inserts cause an (imo) unnecessary "blank" line between two methods in the source code, so it's still not perfect.

In my case I've now got the following keyboard shortcuts set up for hiding/showing documenation blocks:
ALT+A -> fold/unfold documentation block at cursor position
ALT+Y -> unfold all (documentation) blocks
ALT+S -> fold all documentation blocks (this one is provided by my addin, since this is not possible by default)

My question now would be, does somebody know of an addin that would do this even better? Because with my solution you can sill see those unnecessary blank lines/UI controls and it's possible that you accidentally erase a whole documenation block if you're not careful.
(I'm stricktly speaking of visual studio here, I know that other IDEs provide this feature out of the box )

What do you think about the topic, do you know other solutions/workarrounds/visual studio addins?

Cheers

[stoneCold]

In case someone wants to try out the mentioned addin...
here's the download.

The addin basically searches for block comments that end with:
<tab>*/
or
<space><space>*/

...and then folds those blocks.
(single line comments such as /* a single line comment */ will be ignored, unless there's two spaces before the ending */)

Since M$ didn't provide the necessary inferfaces for properly implementing such an addin, this approach is kinda hacky, but it works at least

Cheers

[_tommo_]

Well, documentation is too useful to even leave it folded in a little box... often just reading my own comment for a method i remember better how it was suppposed to be used.

So i'm more often using the alphabetical method dropbox or the Class Layout menu to locate members and methods... it goes along well with comments, and it's just faster

[stoneCold]

Yeah, I do so as well most of the time, but that only works if you know what method you are looking for. If you want to see a complete list of the methods which are declared in the current file, you have to view it in the visual studio "class view" or what it's called, and that involves quite some mouse clicks etc.
I really like to have header files which I can easily browse for method declarations and to be able to see the full list of methods which are declared in the current class/header.
Adding inline documentation really interferes with those wishes, therefore I quickly created the above addin

[mr. iknoweverything]

i have to say, i always found the idea behind CWEB to be awesome, however, i gues you would end up spending more time formatting comments than actually writing code

[xavier]

Inline documentation is a curse, period. It's a way for programmers to feel like they are producing documentation, when in fact, they aren't. They are making notes to themselves and to other developers of the code in question. Actual documentation (see MSDN for an excellent example of real documentation) requires constant review and update to ensure that it is current. When was the last time you (where "you" equals "gentle reader", not specifically anyone in this thread) did a documentation review on your comments? Indeed, when was the last time you updated a comment when the code changed?

There is no "fast buck" to be made in documentation. For it not to suck, it takes a lot of effort, and none of that should be reflected in the size of code files.

And in practice, the wrong people to create documentation for a code API are the ones writing the code. Think about it -- you know how the code works, so therefore there are things obvious to you that are not obvious to a new user to your code/API. They invariably get shafted by the programmer's cursory attempt at documenting the API in code comments. And no, "read the code" doesn't count (it's yet another cop-out for the programmer, same as someone keeping their code at some artificial "0.x" version so they can cop-out ad infinitum that "it's still under development").

Never the twain shall meet -- let code files contain code, and let someone else (not the code developer) write and maintain the documentation. Why someone else? Because if the person writing the docs has some questions about something in the API, they will ask, and the answer will be documented for the ages. I've not once found this to be true for inline docs.

Selah.

[stoneCold]

Very very true, imo.
I'm currently investigating how possible it would be to use Doxygen with non-inlined documentation, if I understood it right this should be possible by creating "documentation only" headers and using Doxygen's special commands for external documentation...

* \struct to document a C-struct.
* \union to document a union.
* \enum to document an enumeration type.
* \fn to document a function.
* \var to document a variable or typedef or enum value.
* \def to document a #define.
* \typedef to document a type definition.
* \file to document a file.
* \namespace to document a namespace.
* \package to document a Java package.
* \interface to document an IDL interface.

Which is already far better than inlined documentation comments, but still not the holy grail of managing documentation.
I'd be really interested what methods/tools for documenting code you are referring to xavier, do you know of any (preferably free) documentation tools which cleanly seperate code and documentation ?

[Wolfmanfx]

What i have seen in big engines projects like Gamebryo / Trinigy Vision is that the use inline (header) documentation. For example in C# inline doc is super because this one is shown with VS intellisense.

[betajaen]

I gave up documenting NxOgre with Doxygen a few months ago. I found it to be too cumbersome, and the output it gave wasn't particularly good, and I couldn't really customise it.

So I made my own; It's called Bread.

It is literally a self-contained 700 line python file, that is run after a compiling NxOgre. All it does is scans the header files for comment blocks, assumes them to be using the textile formatting, so strips them out, cleans it up and creates files out of them. The NxOgre source code is managed by GitHub, and it will automatically turn any textile file into HTML once you view them, so it doubles up as a manual when you view the source.

There are a few cheat codes to help with organisation, but all it boils down to is:

Code: Select all

  /*! function. getWorld
      Get a copy of the World pointer.

      return. World* -- The World instance, or NULL if the World has not been created yet.
  */
   static World* getWorld();

It is easy to read, without skimming over silly javadoc codes, and Python can go through the entire source code in a few seconds.

Of course it doesn't solve the whole inline documentation thing, but at least it helps.

[sinbad]

I both agree strongly and disagree strongly with xavier's point at the same time. Sure, everyone would love to have dedicated, separate, constantly audited documentation, but that's just not realistic.

Inline documentation has some major advantages:

1. It exists. Too many programmers don't write any documentation at all, and the mantra "someone else should do it", or "it should be separate" just means it won't get done at all unless your company is large enough to have dedicated technical writers on staff - and in my experience that means you have to have at least 100+ employees before you go to that length. Making programmers write documentation as they go at least means it's there at all.
2. Code hints - standard inline documentation shows up in tools like MSVC, Visual Assist and XCode when you use the auto complete. This is vastly more useful in the majority of cases when you mostly know what you're looking for but need to check a few specifics, than having to go look in separate documentation which breaks your flow.
3. It's a contract. Actually writing out what a method should do before you write it is very good practice. TDD is all well and good, but there's nothing quite like writing something out as if you're explaining it to someone else to clarify your thinking before you start cutting code.

Of course, for orientation, more significant codebases, cross-linking, context, diagrams and lots of other reasons dedicated documentation is king. But it doesn't mean you shouldn't write inline documentation, you should do that AS WELL, and it will usually come first. Hell, it will probably be the bones around which your technical writers, if you're lucky enough to have them, will write the 'real' documentation anyway.

[mkultra333]

Wait... is xaviar saying we shouldn't comment our code? Or is there a subtle difference between commenting code and "inling documenting" code?

[madmarx]

I disagree with xavier.
How I work :
First I write an example of code of what I would like to have in the end, with explanation. Then I describe the classes. All of that is in a .h, which will saved in the svn. Even if someone comes and say we will now work 3 weeks on something different, my thoughts are already in the code, and even my coworkers can re-read it. Then comes the development. I write first my .h, and then the .cpp if any. Most of the time, there is a few differences with what I had forseen. Some changes in the design are added after the first comment (nothing removed) in the beginning of the .h to specify changes in the design, and why. I can have big .h, but I don't have the least difficulty to maintain it up to date. I always put example of use for systems (ex: a inter process communication system, a sound system), and if I have time and possibility, I write the unitary tests.

If I come back on the code, with my debugging tool, on the pc of a client on a project I did not touch the 12 last months, it is a gift to find the comments and description while debugging, because it makes the "remembering" so much easier.

The key in commenting is to describe precisely anything (a param, a value, a member) that could be ambiguously understood, even by myself. Example: If I read 'width of a window', I precise in the comment that it is in pixels, and not in percentage of the screen. I use Doxygen to do the comments, but not for templated classes.

I use that for a some years now, and I learned recently that there are guys who created agile methods (eg : Scrums, Extrem programming). They said that heavy inline documentation is the way to document things : easy to communicate. And external documentation is a pain to maintain.

So I am for 1/ inline documentation 2/ generating some doc with doxygen or something equivalent.

[xavier]

Wait... is xaviar saying we shouldn't comment our code? Or is there a subtle difference between commenting code and "inling documenting" code?

It's not just subtle -- it's rigid. Trying to write comments that are intended for automatic API generation is unfair to both ends. Comments are there to explain unclear code or algorithms, and shouldn't be used for any other purpose (IMO). It's unfortunate that javadoc spawned this whole idea that you can create usable API documentation from code comments, but there you have it, I suppose -- can't put that genie back in the bottle.

[syedhs]

Inline documentation for me is good enough for projects who can't afford to hire full time staff(s) to create something like MSDN. It is good enough for programmers who can see one-to-one relation between member function and documentation that goes with each of them. And the doc got generated automatically by tools like doxygen and considering that they are also used by programmers, they are good enough.

We have to draw a border between cost and usefulness and I think what we have strike a good balance between both.

[Klaim]

I agree more with Sinbad than xavier but I see your point xavier.

In fact, with extreme seperate experiences of documenting in code, documenting separately and not documenting at all, I think the problem is more that you cannot apply documentation in code the right way for all type of code (even in a unique software). It's good for API of libraries or other type of systems used by more than one module of a software. Other than that it's more like forced comments -- "because it's the rule...". So now I add documentation in code only on headers, only to say what's a class concept and add description of non-obvious member functions (or global functions). Now, for some systems I prefer to write the "right" behaviour and usage in plain english first while writing the system API and THEN write the the implementation once the interface of the system seems right for the job. I almost don't comment at all experimental code where I'm trying to implement something that I never had experience for and that is not trivial. I then add documentation once I played enough with the concepts to see which code "architecture" will fit my needs -- in fact you can say I don't use documentation on "prototype" code.

The inline documentation might change because of code change and this point made me understand that inline documentation is "code" too and should be treated as such.
What I mean is that you inline documentation should not use any non-abstract type name, or any variable name but instead should explain the conceptual view of what's the code will do (in headers only, I'll never use doc in cpp).
You know that your variable names and functions names might change in time so using them in documentation is like puting a mine in the comments for future readers. Instead, the documentation should be a guide because it tells what the user should expect.
The inline documentation should be treated as really high and generic code that runs only in developer's head, not as somme kind of tutorial for a class or function.

My 2 cents.

[stoneCold]

I agree with xavier on the points...

• documentation shall be clearly/physically seperated from code (inline documentation blocks are a no-go imo since they tend to make the actual code unreadable)
• trying to create API documentation by adding inline documentation blocks on the go, will not yield good results, especially when you are using agile development methods.

...but I also agree with sinbad on the following...

• It exists: it's by far less complicated to add documentation by providing c++ block comments, than using a documentation method which is completely decoupled from the actual code. Therefore chances are good that the developers of the code/you will create at least very basic documentation comments for each and every function.
• Code hints: of course it can be useful for developers to see short descriptions of classes/methods/etc. right inside the IDE, so ruling out inlined documentation completely won't do good either

Currently I'm trying to compose my very own solution to the topic, basically I'm planning to do as follows...

1) headers that contain the actual class declarations are only allowed to contain doxygen "\brief" documentation blocks (one liners). These comments provide the developer's IDE with the necessary information to display the short info tooltips that sinbad mentioned.

A typical code header will look as follows...
vtxRoot.h

Code: Select all

namespace vtx
{
	/** \brief The root class of the vektrix library */
	class vtxExport Root : public Singleton<Root>, public FactoryManagerNULL<MovieFactory>
	{
	public:
		typedef std::map<String, Movie*> MovieMap;
		typedef std::vector<Plugin*> PluginList;

		Root();
		virtual ~Root();

		// overridden from FactoryManager<MovieFactory>
		bool addFactory(MovieFactory* factory);

		/** \brief Load a plugin from a shared library */
		void loadLibrary(const String& name);

		/** \brief Register a Plugin to the vektrix library */
		void registerPlugin(Plugin* plugin);

		/** \brief Create an instance of a movie */
		Movie* createMovie(const String& name, const String& filename, const String& factoryname);

		/** \brief Method to update all underlying subsystems and movie instances of vektrix */
		void update(float delta_time);
...
...
...

2) The more detailed descriptions for classes/methods/etc. shall be stored in seperate files and in a completely seperated directory structure (code vs. documentation). The files that contain the detailed documentation shall be named similar to their "code" counterparts (in the above example, the documentation header for vtxRoot.h could be named docvtxRoot.h/vtxRoot.doc.h or anything along those lines)

A documentation file would then look like this...
vtxRoot.doc.h

Code: Select all

/**
\class vtx::Root

The Root class is the class that gives you access to all
underlying systems of vektrix and therefore has to be instantiated
before you can use any of these. Its main tasks are the creation & 
destruction of movie instances as well as the loading & unloading of plugins.
The unique instance of the Root class, once constructed, is accessible via 
the getSingletonPtr() method.

\fn void vtx::Root::loadLibrary(const String& name);
@param
	name Name of the plugin that shall be loaded

\fn void vtx::Root::registerPlugin(Plugin* plugin);
@remarks
	Only plugins that are registered to Root will be properly unloaded at the shutdown of vektrix
@param
	plugin The Plugin that shall be registered

\fn Movie* vtx::Root::createMovie(const String& name, const String& filename, const String& factoryname);
@param
	name A unique name that can be used to retrieve the movie instance from vtx::Root after creation
@param
	filename The file that defines the behaviour and appearance of the movie
@param
	factoryname The factory that shall be used to create the movie
@returns
	A pointer to the created vtx::Movie instance, NULL if an error occured

\fn void vtx::Root::update(float delta_time);
@param
	delta_time Time that has passed till the last update
*/

I agree that the documentation file structure can be a bit difficult to look at, not to speak of editing it and keeping it in sync with the actual code.

3) That's why I'm currently investigating how much work it would be to create a simple "VisualDoxygen" addin for visual studio, which will keep track of the documentation files in a more elegant way.
Basically the addin shall provide a more or less pretty interface to add documentation to classes/class methods/etc. and it would also have to keep the "documentation headers" and "code headers" in sync.

4) To generate your final documentation you simply provide doxygen with both, the directories containing your code, plus the directories containing your documentation headers.
Winner winner, chicken dinner

Imo this would end up beeing a quite pretty solution, since it does clearly split code/documentation and keeps documentation and code in sync.

[syedhs]

Actually TBH, I don't find lots of comments in the header to be nuisance or hindrance of any kind. Maybe it is a personal thingy, and probably it is not ideal enough but I can live with that (documentation in the header).

Providing external file for documentation purposes sounds not much difference than the 'traditional' method of documenting - a separate MS Word file, with the author (not the programmers) looking up at the header file, trying to document all them. This practice although is the best, can easily be out-of-sync with the actual class definition, unless it is constantly updated and this requires more resources ($$$ )

[nikki]

I think one main thing that inline documentation misses out on is 'conceptual' documentation. Like, what the Ogre Wiki (the tutorials especially) show. It's great for code documentation though - I usually find it easier just 'jumping to the definition of a function' and reading the comments around it.