Documentation Software

[Archangel-Tyrael]

With KDevelop having doxygen in the package, i think it would be "neat" to have a documentation software come along codeblock's default installation package

The most popular documentation software are

-doxygen(used by kdevelop)
Support for c/c++,java,python and partially php
Not so proffesional look(personally i find its "default" presentation annoying to read)
written in c/c++

-Doxys
Support for c/c++ only
Very proffesional look
fork of doxygen thus written in c/c++(i saw some python scripts too..)

-Natural Docs
Support for many languages and easilly expandible
Really Neat "natural"  Documentation style
Proffesional look but i dont think it would look as good in chm?
Written in perl...(thus need of perl interpreter...)
Has differential building( if you run Natural Docs on the same source tree, same command line options, and without changing configuration file,it will only update the files that have changed,which is very helpfull compared to full recompiles of the other two)

I prefer Natural Docs, though i guess the requirement of perl interpreter and (the already buildin) documentation highlighting of doxys&doxygen would possibly make doxys a better canditate?

[takeshimiya]

Doxygen: I never liked the output produced, it's very user unfriendly.

Doxys: I like a lot the output produced by it. So much that I've made the SDK reference with it here: http://forums.codeblocks.org/index.php?topic=1358.0

Natural Docs: I like a lot the "natural" style of writting for, I think it's the best approach, but for me perl==no, so I don't know how the output looks.

[Michael]

Hello,

In my experience, Doxygen is oft used by developers for Academic and Industrial domain. In every project, I have participated Doxygen was used (more or less), even if it was not a mandatory requirement. Personally, the output is not very easy to understand .

Concerning Doxys no idea. I never tried it.

Natural Docs sounds good, but regarding Perl, I would say no thank you. I use scripts only when I absolutly have. But this is me .

Michael

[yop]

Concerning Doxys no idea. I never tried it.

You can get the cb sdk documentation generated by DoxyS that Takeshi Miya built from the link in his post. I never heard of Doxys before but following his howto I built the sdk documentation and now I can't work without it (I have also loaded it to the help plugin and I get a search in documentaion right click entry, how great is that?). The output IMHO is by far better that Doxygen.

[thomas]

What is documentation?

[280Z28]

For a public API, writing the API on a Wiki and then developing the library to work as stated is quite effective. Trac has helped me integrate that quite easily into one of my projects.

[Michael]

You can get the cb sdk documentation generated by DoxyS that Takeshi Miya built from the link in his post. I never heard of Doxys before but following his howto I built the sdk documentation and now I can't work without it (I have also loaded it to the help plugin and I get a search in documentaion right click entry, how great is that?). The output IMHO is by far better that Doxygen.

Thank you for the info. Yes, I have read the post of Takeshi Miya. At the time, I have just downloaded the CHM version and used it with the help plugin. I will give a try to Doxys.

Michael

[takeshimiya]

In a perfect world we would have: the output produced by DoxyS, and the comments style of Natural Docs, being the program written in C++.

We could call it Natural DoxyS

BTW, I know another documentation generator, DocJet, which uses the same ideas, but it's more intelligent. Too bad it's commercial.

So for now, I would keep using DoxyS.

[Game_Ender]

The advantage of the systems listed here vs the "Write an API and fulfill it" method is that they documentation is kept with the code, which means it much more likely to be kept up to date with what the code actually does.  I have the most experience with Doxygen myself, and I don't have much of a problem with its output style.  I think it would be great to have a plugin that included as many as possible, that way the user could decide.  I don't think it that much work to whip up a GUI that lets you select all the proper options.

I think it should be a two level selection, the first being the style of the documentation comments you wish to use, and based on that the plugin makes available what ever processors are available.  For the options given in this thread you would have "Natural Doc" style, and the "Doxygen" style.  For the Doxygen style you could either use Doxys or Doxygen to generate the output, and with Natural Doc style I guess you would only have the Natural doc style.

I don't know whether it would be best to invoke these programs or have the compiled into the program.  It would probably be easier to just invoke the external executable, and include a compiled version of the program with the binaries and instructions on how to get/compile it for the SVN version.

[takeshimiya]

A documentation generator plugin should be easy to write, with support for all the documentation systems talked here.

[Archangel-Tyrael]

Game_ender thats exactly what i am suggesting

Takeshi: A simple gui to communicate with doxys/natural docsplugin is neat, but i am askingm is that the binarys should be distributed with the default setup program (like code::block does for wxsmith,code completetion etc does right now)
The binarys are small anyway (3 mb for doxys &335 kb for natural doc)
-i dont think we need doxygen as doxys is better atm and uses the same commentation style thus they overlap each other

In any case it would  be really neat if we could have Natural Doxys made by us ,so i took the courage and emailed doxys devs to get some information on how hard it would be to(it shouldnt be hard but just making sure) to add additional commenting styles(natural doc style)

Waiting for theyr reply

For the moment i would really like to hear from Yannis if he agrees with this concept,because i really think that to "compete"(and get additional programmers to expand code:blocks) and be a complete c++ IDE we will have to follow some succesfull additions from other packages like KDevelop(especially if they are so easy to add)

[mandrav]

For the moment i would really like to hear from Yannis if he agrees with this concept,because i really think that to "compete"(and get additional programmers to expand code:blocks) and be a complete c++ IDE we will have to follow some succesfull additions from other packages like KDevelop(especially if they are so easy to add)

The first step is to create a working plugin. Once it is done, I 'm sure we 'll find a way to distribute it either by including it in the setup or by providing access to it through other means (probably the auto-update channel we will soon start to work on).

[killerbot]

Hi,

I am already working on a doxygen plug-in, I will continue on it shortly, but first I am tryin to help to fix some other bugs in CB.

Cheers,
Lieven