Doxygen

[chrisname]

Who else uses Doxygen? I just started using it today; it's pretty cool, but is there anything better? I've heard it has a lot of bugs.

[Mythios]

I personally hate Doxygen. I had to use it for a year. I didn't find it complicated or anything, I just found it had some screw ups and annoying things. I can't really remember what they were but I just remember I hated it. With that being said I should probably go get it again as I haven't used it in a while and see if it's any better now.

[Return 0]

I'm not too fond of it. It's not a bad tool and it's free, I'm just used to enterprise solutions.

[Duthomhas]

A lot of people use it, and it is nice.

I hit its limitations very quickly... And it requires a lot of learning to get going...
Since my projects are usually home-brew, I just write my own documentation the way I like.

[Mythios]

How exactly do you hit it's limitations. What doesn't it have that you're wanting to do?

[Disch]

One problem Doxygen has that I couldn't figure out a way around was how it treated overloaded functions as their own function. For example say you have the following:

void SetRect(int l,int t,int r,int b);
void SetRect(const Point& tl, const Point& br);
void SetRect(const Rect& rect);

I would want the documentation for these functions to be done similar to the way the standard lib is documented on this site.

see here for an example: http://cplusplus.com/reference/clibrary/cmath/cos/

That is... the above 3 prototypes would be layed out, followed by the parameters for all overloads, followed by a common description / explanation for all of them.

AFAIK, in Doxygen, this can't be done (or at least I couldn't figure out a way to do it). And instead each overload is treated like an entirely seperate function, and the description / explanation / etc would have to be duplicated for each one.


That was my only major beef with Doxygen... but then again I don't have a lot of experience with those kinds of programs.

Can anyone recommend good alternatives?

[Mythios]

I recall having the same problem. No idea for some alternatives though - I just keep my code neat and comment my header files. No need to generate stuff for me at the current time anyway.

[chrisname]

I comment both; but with a different style. I write "Doxygen comments" in my header files and then write "people comments" in implementation files, with the idea being that Doxygen need only look at .h[pp] files (I use .hpp for class declarations and .h for general header files) and people read the comments in my implementation files.

[Mythios]

Actually now that you bring that up, I've never used a .hpp file. Whats the main purpose of them?

[Disch]

there's no difference between .h and .hpp. It's just a style thing.

[Mythios]

Is there at any point where you should use one over the other though?

[moorecm]

The preprocessor simply includes text files. They could be named anything you want (asdf, asdf.exe, asdf.h, asdf.hpp, 123, etc.)

I think .cpp & .hpp or .c and .h depending on C++ vs. C code is a good rule of thumb.

EDIT: I guess it's worth mentioning that the source file extension does have significance to the compiler. man gcc to find out the supported file extensions and how they correspond to different languages.

[z05DSL3A]

Is there at any point where you should use one over the other though?

Not really. I used to use .hpp for headers that could not be used with C.

[moorecm]

Not really. I used to use .hpp for headers that could not be used with C.

I do the same thing. If I want to make C++ functions accessible in C code I'll wrap the funtions in an extern "C" and put them in a .h file just as a little visual reminder...

[Mythios]

Alright, cool, thanks guys.