Clang based documentation generator for C and C++ | Hacker News Reader

Clang based documentation generator for C and C++

jessevdk.github.com

75 pointsjkn20 comments

Will it be doxygen compatible ?

Most of our C and C++ code is documented with what's pretty close to Javadoc comments, which is one of the flavors doxygen understands. We are certainly not going to rewrite comments for another tool even if we'd like to use that tool.

Pretty much all code I've seen that's documented to be used with a documentation extraction have been doxygen, or some flavor that doxygen can handle.

Partial support for other formats is planned. It's quite obvious that all currently documented C++ is using one of the existing formats and that it's nonsense to expect people to convert their already written documentation. The question is exactly how much of the other types of syntax needs to be supported to be useful.

clang already supports the doxygen/javadoc commenting itself. At least, it has a warning named -Wdocumentation in the latest release from Apple that tells me that in my documentation I have a variable that is not anywhere in the function signature!

This is the key question. In an ideal world it would parse Doxygen-compatible comments and output to the Doxygen XML file format so it can then be rendered by Doxygen's HTML generator. Keep this tool focussed on the parsing etc. and let Doxygen continue to do what it does well.

In my mind Doxygen is a fantastic tool and its only drawback in my experience is its slightly simplistic parsing engine which means it's slow to adapt to new language features.

The documentation is completely unreadable in IE7 (which while I'll admit is not Google Chrome, it's also not IE6 or Netscape 4). By 'completely unreadable' I mean nothing shows up at all except an empty sidebar.

Whatever happened to "graceful degradation"? This isn't a ticket-buying website, this is simply API documentation.

Edit: Plus, if it doesn't work in IE7 I really don't think it will work in lynx/links/etc.

I'm happy this project exists. For generating Objective-C documentation, there is the complex Doxygen, and the light https://github.com/tomaz/appledoc. Appledoc unfortunately lacks too many features. As it is built on its own home-built parser... well improving it sounds like patching a leaking corpse. Going with Clang sounds pretty sensible. However cldoc does not support Objective-C (yet?). This is how I interpret the many `Unhandled cursor: CursorKind.OBJC_CLASS_REF` messages I get. Stay tuned, this may be big.

Would be nice to see clang somehow generate a 'cscope' compatible database.

This would make cscope much more reliable for C++ projects (cscope VIM/emacs plugins are very useful for efficiently navigating a large source tree).

cscope is an amazingly useful tool for a C developer, even without using an associated editor plugin. I was very impressed by its speed years ago when I could instantly look up the definition of any symbol in the Linux kernel (IIRC - it's been a while since I've had occasion to use it).

Agreed. Cscope is pretty damn fast & handy. I use it with the vim plugin when doing Android dev and it works well to quickly look-up definitions. What I find most impressive is how fast it builds the references. I can essentially build a cscope.out file for the entire Android project in under 4 minutes. The only thing I've had trouble with is getting the Java tags to work. Anybody else know how to set that up?

I have some interest in this as well. At least in the case of vim, there are completion plugins based on clang that work quite well, but for some reason they don't support navigation right now. Just being able to "go to definition" is a big deal.

I like 'ctags' for the editor integration (vim) -- never got a handle on cscope's interface.

Cool idea. Back button appears to be broken in Chrome. Pushing the back button makes the URL change but not the content.

Awesome idea! I'll experiment with it in my projects. Doxygen is horrible, and looking at your example I can see it's far superior than Doxygen.

That depends.. it would be more helpful to evaluate comparing to Doxygen if a more meaty C++ example was used. This is our std::vector implementation (below). The STL provides enough meat for any doc generator to chew on...

http://bloomberg.github.com/bsl/group__bslstl__vector.html

I'm no fan of Doxygen output, but it is used because it has proven to be the most robust for documenting complicated code.

edit: links

Wow, I am green with envy after looking at those docs! I wish the LLVM/Clang doxygen was that nice. You are lucky if you get any comments at all.

Can you explain why you think that doxygen is horrible?

The HTML output.

What is wrong with that?

It looks like shit.

Did you know that the output can be customized in many ways, for example using CSS and templates? Many organizations use doxygen for their documentation, even though you wouldn't recognize it at first.

Also, whether the tool uses clang or a custom parser doesn't affect the HTML output in any way. I agree that using clang is interesting, but you seem to be depreciating Doxygen for all the wrong reasons.

Reply on news.ycombinator.com