Code documentation editor

Question

I've been looking for a code documentation editor app. I don't mean just a generation tool like doxygen, but an application that allows me to edit the documentations and change it directly at the code.

Does anyone out there know of a good editor?

Thanks!

Answer 1

If you're talking about Visual Studio...

I've written an add-in, AtomineerUtils Pro Documentation, which will help a lot with documentation creation & editing.

• To create comments, the addin uses as much information as possible from the code element you are documenting to fil in a skeleton documentation comment for you. It tries hard to provide useful information in a readable English form (so tries to generate meaningful docs, and documents a lot of things that are not immediately "obvious" from the code itself, like exceptions a method throws)

• To update comments it can sync the comment with the code - so if you add/remove/rename parameters, change the exceptions thrown, etc, it will update the comment to accurately reflect the new state of the code you're documenting.

• It applies configurable word wrapping, whitespace control and block formatting to help keep the comment blocks tidy, well formed and consistent.

• It supports loads of lanuguages (C++, C, C++/CLI, C#, Java, VB), Xml Documentation, Doxygen, Qt and JavaDoc documentaiton formatstyles,

If you want a documentation system that provides WYSIWYG editing of documentation without going near the source code, then I believe something more like Document!X may suit your needs better (I believe you'll have to write all the documentation yourself, but it is aimed more at authoring external documentation than providing in-code documentation)

Of course, for your language/platform/editor preference these may not be applicable, but there are other similar products around, once you get an idea of the right sort of search keywords to use, so hopefully these might give you some leads.

Answer 2

Use a code editor and auto-fold the function bodies so you can't see them. It is the simplest way to do what you want to do. You'll have to manage version control as well, sorry to say.

The problem is that the code (and comments) are in version control and that needs to be tracked. You cannot get around it.

For what it's worth, you see a logical difference between editing the code and the comments, but you are editing the same files. Programmers see no difference between these to things and will be really confused by your terminology. I suspect they will argue with you about it incessantly too, but really its just the words you are using.