At the end, no documentation is generated. I don't know if it's because the functions aren't actually documented in the source or if it's because of errors?
I don't really want to litter the source with a lot of documentation for the functions. I want to keep it separate in a help file instead. I don't know if doxygen is right for this, though.

Mario F.

04-11-2008, 04:28 PM

Yeah. Doxygen will require you to comment your code. However that's not the reason why you are getting those errors. Doxygen will function just fine as an indexer without any kind of commenting. I do wonder though why you don't want your code commented. With certain care, smart IDE color coding choices, and well placed code folding, I've been able to fully document code in the past for Doxygen without it getting in the way.

Anyway, the problem seems related to Graphviz' Dot tool. You probably don't have it installed and opted for generating graphical representations of your code structure and relationships. Quite nice that tool, I must add...

Right. So,

Check here for some general info http://www.stack.nl/~dimitri/doxygen/diagrams.html

And here http://www.graphviz.org/Download_windows.php for the actual thing. Then it's a matter of configuring Doxygen... which I don't remember how. But it isn't hard.

Naturally... you can also opt to not generate those graphs and diagrams making also sure you have HAVE_DOT set to NO on doxygen configuration.

Elysia

04-11-2008, 04:48 PM

Actually, I wanted to keep it separate since comments take up a huge portion of lines in the code.
And generally, I do like function prototypes to be spaced together, after each other, since it enhances readability.
But thanks for the links. I'm going to check it out tomorrow.

dwks

04-13-2008, 11:50 PM

Note that with Doxygen, you can put the documentation for any entity anywhere. There are special commands, like @file or \file, which let you refer to exactly what it is you are documenting. (Commands exist for referring to functions, classes, variables, etc, I just don't know them offhand.)

Personally, I would recommend putting your documentation throughout your code for several reasons.

Doxygen comments are often quite technical, and would be very useful for people reading your code. People don't like to switch between files all of the time. These comments are much more likely to be used if they're conveniently placed right at the entities they document.
Putting your comments elsewhere means that you have to basically duplicate the signatures of your functions or whatever in another file, making renaming functions or other identifiers that much harder.
It's not that big of a hassle to put the comments inline. With syntax highlighting, you can easily skip over large sections of commenting. You can also use code folding as Mario F. suggested. (I think he suggested syntax highlighting, too.)

Also see this, from the Doxygen manual: http://www.stack.nl/~dimitri/doxygen/docblocks.html

Documentation at other places
So far we have assumed that the documentation blocks are always located in front of the declaration or definition of a file, class or namespace or in front or after one of its members. Although this is often comfortable, there may sometimes be reasons to put the documentation somewhere else. For documenting a file this is even required since there is no such thing as "in front of a file".

Doxygen allows you to put your documentation blocks practically anywhere (the exception is inside the body of a function or inside a normal C style comment block).

The price you pay for not putting the documentation block directly before (or after) an item is the need to put a structural command inside the documentation block, which leads to some duplication of information. So in practice you should avoid the use of structural commands unless other requirements force you to do so.
Italics are theirs, not mine.

Elysia

04-14-2008, 12:46 AM

OK, I got it compiling and generating documentation and all that, but the errors mentioned above is still there. Not to mention, for example, it calls CMemoryManagerBase as "abstract< T > Class Template Reference".
And also, if I tell it to just compile documented functions, it shows nothing at all, even though I put a proper comment block before a function and even included the test class on the manual page!
The how of using doxygen still escapes me.

Mario F.

04-14-2008, 05:40 AM

I've ran into some problem with templates and doxygen in the past too. Some issues are still unsolved as you can gather from the documentation and other sources on the website. Others can be solved by slightly altering the placement of your declarations in relation to the definitions. (In fact Doxygen likes it when you predeclare everything).

I'm unsure as to what your problem may be. The template seems simple enough to not cause any trouble. The only thing I can think of is for you to predeclare that template class and see how doxygen behaves. If you do, you may want to comment not the declaration, but the definitions themselves. You may want also to play with some of the Doxygen documentation specifiers like /brief. You will want to red about these. They will keep Doxygen greedy parser under control.

You are not alone. Doxygen takes some time to get used to its idiosyncrasies. You'll learn these quickly enough if you press on, read carefully the documentation, subscribe to the mailing list and experiment. It keeps getting fixed which is good, but its still a tool that can make you want to pull your hairs out in frustration.

Unfortunately I can't help you past this. It's been a good while since I last used Doxygen. I can't remember many of the details. All I can say is that it works. You just need to look at it as a tool a tad bit more complicated than it would appear at first sight, and which will demand some study in the beginning in order to allow you to rip the benefits.

Elysia

04-14-2008, 05:55 AM

I always like to declare/define templates before the actual implementation. Indeed, I have a full definition of all the template classes before the implementation in each file for the class.

But I still don't understand how to get it properly working. I've managed to make it detect classes, but not functions. Inside or outside a namespace, it doesn't matter.

What exactly are you doing? If you're using the command-line only, can you post your whole output of everything from start to finish, not just of running Doxygen, so that I can try it myself? What version of Doxygen are you using? What happens when you try that Doxyfile that I automatically generated above?

Do you not limit yourself to a number of characters per line or something? I've trimmed the output with backslashes.

Elysia

04-15-2008, 02:09 PM

The EXPORT doesn't seem to make a difference. And as you should know, I loathe command lines, so I'm running it from the GUI.
Replacing the file with your file and tweaking some settings to no class diagram (save time), no latex stuff, selecting source & dest directories and running it doesn't seem to help either.
I'm using 1.5.5. Doxygen seems to be a real bastard to get working.

dwks

04-15-2008, 02:47 PM

And as you should know, I loathe command lines, so I'm running it from the GUI.
Yes, I thought you would be. It shouldn't really make much difference anyway.

I'm using 1.5.5.
Well, as you can see, that's my version too.

Doxygen seems to be a real bastard to get working.
On Linux, it was already installed. Presumably you're using Windows, so that might be a bit harder (although when I installed Doxygen 1.4.6 on Windows a while ago, I had no problems whatsoever).

You didn't try compiling Doxygen from source or anything, right? You just downloaded the binaries here? http://www.stack.nl/~dimitri/doxygen/download.html

Also see these notes, though they're probably not useful. http://www.stack.nl/~dimitri/doxygen/install.html#install_bin_windows

dwks

04-15-2008, 03:07 PM

Alright, so I download the Windows installer and ran it in wine (since I'm using Linux). I installed using all the default options, except that I chose not to create a start menu item. I used the GUI to create a Doxyfile, with basically the default options (I just added the paths, to the source code and working directory and so on).

I then ran Doxygen (again, this is all from the GUI). I got an error about not being able to execute dot, of course, just like you did. But I didn't get an error about unique matches, and the HTML documentation was all generated correctly.

Elysia, can you please post the smallest snippet you can create (even if it's big, I don't really care) that will cause Doxygen to fail? I'm guessing you're trying to parse more code than you have.

I don't know if it's a Doxygen problem, but maybe it is. It might be something wrong with your code, I guess -- does it compile without warnings?

Mario F.

04-15-2008, 04:04 PM

I'm guessing this is a problem with namespaces, not the template class itself. I suggest perhaps trying to reproduce the problem with a similar namespace setting.

Remember dwks? Doxygen is still shaky around certain namespace setups. I remember one in particular that would drive me nuts; partitioned unnamed namespaces in the header and source file. I don't remember actual parsing errors like Elysia is experimenting, just failing to document the definitions... but one never knows. So probably it is best to include the namespace setup in that test.

Elysia

04-15-2008, 11:41 PM

Seeing as it failed big time with the real source, I tried to dumb it down to the following:

//! Opens a Open File Dialog (deprecated; use StandardOpenV2)
/*!
This function opens a standard open file dialog with the supplied arguments. This function is deprecated; use StandardOpenV2 instead.
\param strDefExt The extension to show by default
\param strFileName The filename to display by default
\param strFilter Filter to use (extension|name)
\param bMulti True if user is allowed to select multiple files
\param pParentWnd The dialog that is the owner (parent)
*/

Which is exactly what I showed and what Doxygen seems to be failing at.
(Actually, I tried changing the types to see if it would help, but it doesn't.)

The real code compiles w/o warnings and errors, and I'm pretty sure this snippet would too, but I haven't tried it because it's a dummy to try to figure out why doxy is failing.

I'm pretty sure it must be some setting. Remove the namespace, keep the class. It works. Remove the class. It fails.

dwks

04-16-2008, 11:33 AM

Remember dwks? Doxygen is still shaky around certain namespace setups. I remember one in particular that would drive me nuts; partitioned unnamed namespaces in the header and source file. I don't remember actual parsing errors like Elysia is experimenting, just failing to document the definitions... but one never knows. So probably it is best to include the namespace setup in that test.
Nope, never heard anything about it. I mainly use Doxygen for C, which is probably why.

Well, I used exactly what you have posted, and it worked. (This is Doxygen running in wine.) Mario F.: I did, actually. I used the entire code posted, with all three of Elysia's snippets.

I got no warnings, nothing.

The only thing that I can think of is that perhaps the authors of Doxygen accidentally uploaded a version of Doxygen that was broken, and quickly replaced it with a version that worked -- but not before Elysia downloaded the broken one. (Because when I came along and downloaded it a few days or whatever later, it worked.) Maybe you might want to try downloading Doxygen again, Elysia?

Elysia

04-16-2008, 12:13 PM

The only thing that I can think of is that perhaps the authors of Doxygen accidentally uploaded a version of Doxygen that was broken, and quickly replaced it with a version that worked -- but not before Elysia downloaded the broken one. (Because when I came along and downloaded it a few days or whatever later, it worked.) Maybe you might want to try downloading Doxygen again, Elysia?

No... Tried, no workie.
OK this sucks. So any alternative to Doxygen? Free or not doesn't matter so long as it works. Which I can't say about Doxygen.
Obviously free isn't bad, but when it doesn't work then it worse than paid.

Anything specifically for not Linux? As far as I can tell, that's for Linux and it's over-complicated mess of packages and stuff.

dwks

04-16-2008, 01:19 PM

Sorry, that's just the Debian page about Synopsis.

Here's the Synopsis page: http://synopsis.fresco.org/

They have win32 binaries on their download page. http://synopsis.fresco.org/download/

Mario F.

04-16-2008, 01:22 PM

May I suggest, you know, RTFM.
That is the problem. Nothing else. Your settings must be wrong and the documentation explains the settings.

Also... Doxygen has a mailing list that will most definitely help you with this problem. Better and faster.

Elysia

04-16-2008, 01:24 PM

May I suggest, you know, RTFM.
That is the problem. Nothing else. Your settings must be wrong and the documentation explains the settings.
That is not the quality I would like to see in a program. It's definitely annoying.
I'll hold you to it, though. I may scan it a little time and again and experiment, but it will definitely not be fast.

Also... Doxygen has a mailing list that will most definitely help you with this problem. Better and faster.
Probably best advice I've heard. I'll see if I can get in contact with that and patch the question there.