U++ forum: Welcome to the forum

Re: U++ talk [message #17917 is a reply to message #17909]

Tue, 02 September 2008 22:30

cbpporter
Messages: 1428
Registered: September 2007

Ultimate Contributor

Quote:

Doxygen comment are just C++ comment. The C++ parser is optimised to skip them.

I've seen that optimization in practice... (sarcasm)

Quote:

How can people still add new documentation without touching the source code? Well. You will hate me. An applications like linguist (from Qt) use one tool output, lupdate tool (from Qt too), to extract all translation from .cpp and output a xml file. You can then do the translation job on this file with linguist. It's like TheIDE translation tool but with 2 stand alone applications. They don't reinsert the translation, they load it at run time to save memory (only one language for each xml file because with big application you can have several Mo in one file), but, in a documentation tool like Topic++, this metadata could be validated and reinserted by the documentation project manager.

It's not about creating translation (current system is working great) as contributing documentation. Someone has to write the documentation directly in the source code. That means write access is needed, plus someone has to test that it still compiles.
If user has doesn't have write access, somebody needs to merge the changes for him. Also, after every doc commit, people will have to recompile their sources and run doxygen on them. And if you distribute prebuilt documentation, you basically are back to square one.

But I'm also unhappy with Topic++. I would like to have an autogenerated DB style documentation, with doxygen style tags but only for some logical ordering, like saying that function Split should appear on the documentation page "String manipulation function" and on "Strings". Running the topic++ toll would generate all pages in qtf, but would not let you edit only specific parts of the file, like implementation notes and parameter descriptions. Also, if a function is removed, it's attached documentation would be hidden, but the information not lost. You could always pull up a screen with dependency graphs.

But Mirek did not like the idea, so now I'm waiting for his idea and when it is ready I'll write some doc pages and hope that other people in the community will have the patience to manually format a consistent looking help content.

Report message to a moderator