Author Topic: Doxygen plugin  (Read 284898 times)

Offline Cryogen

  • Regular
  • ***
  • Posts: 260
Doxygen plugin
« on: February 19, 2010, 05:31:57 am »
 Hi Guys,

I'd like to announce a new doxygen integration plugin. I call it DoxyBlocks.

I've loved and used doxygen (http://www.stack.nl/~dimitri/doxygen/) for years. I've used Doxbar under VS and missed a similar tool for C::B. Recently, I found jomeggs' doxygen script (http://forums.codeblocks.org/index.php/topic,8213.0.html), which works well but is somewhat limited, and was inspired to create a full plugin to replace it. Since doxygen is the C::B documentation tool of choice, it seemed even more appropriate.

DoxyBlocks provides a toolbar for quick access to documentation commands. It currently provides functionality which creates a doxyfile and extracts the docs, based on jomeggs script but fairly heavily modified. The converted code includes some extensions and some "tidying up" and adds functionality. DoxyBlocks can also insert block and line comments and run doxywizard for more detailed modifications of the doxyfile. It looks like this:


and includes a configuration panel in the editor settings module. All comment types described in the doxygen docs are available.

I plan to add more functionality to allow configuration of the default settings that go into the doxyfile. It might also be useful to add the ability to insert other tag types manually and I plan to look into generating document blocks automatically. I have seen code around that does that. Other things are open for discussion.

The only thing I don't propose to do is write a full replacement for doxywizard. Doxywizard is more than capable and it seems futile to recreate the wheel. My intention is rather to provide reasonable default configuration with some common settings available and defer to doxywizard for the rest. For example, I'd like the user to be able to control things such as OUTPUT_LANGUAGE, EXTRACT_ALL, FULL_PATH_NAMES and ouput types.  With the right balance DoxyBlocks should be able to set things up for you most of the time and you should only need to use doxywizard for access to less common settings. At least that's my hope.

I'm still thinking about one or two things such as being able to enter a custom comment style to be used.

It is already quite usable and DoxyBlocks itself was documented using...DoxyBlocks. :-)

You can find the source by pointing SVN at: https://doxyblocks.svn.sourceforge.net/svnroot/doxyblocks.

The project page is at https://sourceforge.net/projects/doxyblocks/ and a cbplugin is available for download, too.

Thanks to jomeggs for the script and the inspiration.

Cheers,

  Gary.
« Last Edit: February 19, 2010, 06:22:39 am by Cryogen »

Offline JGM

  • Lives here!
  • ****
  • Posts: 518
  • Got to practice :)
Re: Doxygen plugin
« Reply #1 on: February 19, 2010, 06:16:22 am »
Whoa really cool this is a feature that was really needed by codeblocks, a tool that facilitates documenting the code, great candidate to be part of nightly builds  8).

Thanks for your work :)

Offline Cryogen

  • Regular
  • ***
  • Posts: 260
Re: Doxygen plugin
« Reply #2 on: February 19, 2010, 06:26:16 am »

 Thanks, I appreciate that. I certainly hope it will be useful. I'm already finding it very helpful.

 :)

Offline killerbot

  • Administrator
  • Lives here!
  • *****
  • Posts: 5489
Re: Doxygen plugin
« Reply #3 on: February 19, 2010, 10:14:56 pm »
in case  this works well, might be interesting to add it to our contrib plug-ins section in our source tree, and provide it with the upcoming release :-)
I will test it out too.

Question : does it work under windows and linux ?
One thing that won't be able I think under linux is the creation of chm's.
« Last Edit: February 19, 2010, 10:52:49 pm by killerbot »

Offline codeur

  • Multiple posting newcomer
  • *
  • Posts: 113
    • Code::Blocks EDU-Portable
Re: Doxygen plugin
« Reply #4 on: February 20, 2010, 07:24:06 am »
Hi Cryogen,
The ".cbplugin" you provide fails to load with my current version built from a recent svn (6113).
Unfortunately I have no time currently to attempt to rebuild it for the current version, as (by looking at your project) your installation looks quite different and the project options would require a fair bit of editing, but I thought I'd let you know.
« Last Edit: February 20, 2010, 08:06:33 am by codeur »

Offline Cryogen

  • Regular
  • ***
  • Posts: 260
Re: Doxygen plugin
« Reply #5 on: February 22, 2010, 07:32:34 pm »

 Hi Codeur,

Thanks for trying it. A .cbplugin is just a zip file with standard C::B paths in it. There is nothing specific to me in there. I have no idea why it would fail for you other than if things have changed since your version. If you'd like to provide some details such as exactly what fails and what messages you receive, that would be helpful.

Actually, this raises the question of whether a plug-in built with a recent SVN will run in 8.02. Does anyone know?

As for the source, it's built with SVN version 6130 so I'm wondering whether your version may not have recent features such as the extra code field in wxSmith, which you will definitely need. All paths are created using $(#cb) and $(#wx) so, again, there's nothing specific to me in there and (intentionally) no effort required on your part other than to have those variables set in your IDE. Other than that it's a bog standard, C::B-created plug-in project. :-) It does use the AutoVersion plug-in.

If you could provide the details and try upgrading your version and report your results that would be appreciated.

Thanks.

Offline Cryogen

  • Regular
  • ***
  • Posts: 260
Re: Doxygen plugin
« Reply #6 on: February 22, 2010, 07:43:07 pm »
 Hi Killerbot,

 Thanks.

I should know later today. That should answer the 8.02 question, too. The CHM is currently only run under windows and, as of the version I'm about to post, can be controlled by preferences. There are options for running CHMs under Linux. wxCHM, for example, or you may be able to do it under WINE. The plug-in itself should work without issues. Other than the one conditional call to run the CHM it's all platform-independent. The only problem might be if there have been some incompatible changes in the SVN code. I'll let you know.

Cheers,

  Cryo.

Offline Cryogen

  • Regular
  • ***
  • Posts: 260
Re: Doxygen plugin
« Reply #7 on: February 22, 2010, 09:25:29 pm »
 Hi Guys,

I've now uploaded a new version that adds quite a lot of new functionality:

22 February 2010
   released version 0.2.172 of DoxyBlocks

     Change log:
        -Fixed: Bug that stopped the "Run CHM" pref from working.
        -Fixed: Bug that stopped the "Project Number" pref from working.
        -Added: The ability to run the HTML and CHM from the toolbar.
        -Fixed: Bug that caused a crash when using the plugin without a project open.
        -Added: Doxyfile default prefs configuration.
        -Added: Access to configuration from toolbar.
        -Added: Ability to overwrite doxyfile either silently or after prompt.
        -Added: Option to control whether CHM is run after compilation.

I wasn't thinking before but I should point out that this version is only for Windows i.e. it's a dll. I'll be looking at Linux later today.

 Cheers.

Offline killerbot

  • Administrator
  • Lives here!
  • *****
  • Posts: 5489
Re: Doxygen plugin
« Reply #8 on: February 22, 2010, 10:16:54 pm »
Hi Killerbot,

 Thanks.

I should know later today. That should answer the 8.02 question, too. The CHM is currently only run under windows and, as of the version I'm about to post, can be controlled by preferences. There are options for running CHMs under Linux. wxCHM, for example, or you may be able to do it under WINE. The plug-in itself should work without issues. Other than the one conditional call to run the CHM it's all platform-independent. The only problem might be if there have been some incompatible changes in the SVN code. I'll let you know.

Cheers,

  Cryo.


in linux version would be nice to try to incorporate the wxchm (i don't knwo it, but it sounds interesting) :-)

Offline rcoll

  • Almost regular
  • **
  • Posts: 150
Re: Doxygen plugin
« Reply #9 on: February 23, 2010, 02:27:08 pm »
in linux version would be nice to try to incorporate the wxchm (i don't knwo it, but it sounds interesting) :-)

A *.chm file is compiled HTML; does linux have a way of reading those?

Ringo

Offline Jenna

  • Administrator
  • Lives here!
  • *****
  • Posts: 7255
Re: Doxygen plugin
« Reply #10 on: February 23, 2010, 03:26:43 pm »
in linux version would be nice to try to incorporate the wxchm (i don't knwo it, but it sounds interesting) :-)

A *.chm file is compiled HTML; does linux have a way of reading those?

Ringo


Yes, several apps that can read chm-files are available on linux.

Offline JGM

  • Lives here!
  • ****
  • Posts: 518
  • Got to practice :)
Re: Doxygen plugin
« Reply #11 on: February 24, 2010, 01:55:41 am »
a chm file could be said it is a zip file with the files inside organized in a standar way

Offline codeur

  • Multiple posting newcomer
  • *
  • Posts: 113
    • Code::Blocks EDU-Portable
Re: Doxygen plugin
« Reply #12 on: February 24, 2010, 12:59:49 pm »
Hi Codeur,
. . .
If you could provide the details and try upgrading your version and report your results that would be appreciated.
. . .

Thanks for trying to guess why I am having this issue. I do not myself have time to investigate this, so I am not asking for help on this.

Just to answer your question, The error I get when installing the .cbplugin is:
------------------------------------------------
"one or more plugins were not installed successfully:
G:\down\Program........\DoxyBlocks.cbplugin"
------------------------------------------------
A pop-up windows comes up from the task bar:
-------------------------------------------------------------
One or more plugin were not loaded.
This usually happen when a plugin is built for a different version
of the Code::Block SDK. Check the application log for more info.

List of failed plugins:
DoxyBlocks.dll
-------------------------------------------------------------

Obviously this does not tell us much new. (Except that it is an answer to your question: A plugin built from a recent svn is very unklikely to run in CB 8.02.)

It also tells me that upgrading my version would indeed probably fix the issue. I'll do that sometime, but don't hold your breath as this is an installation common to about 200 people. I do not change it just to install a new plugin, even one as useful as Doxygen.


Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9694
Re: Doxygen plugin
« Reply #13 on: February 24, 2010, 01:12:14 pm »
I've now uploaded a new version that adds quite a lot of new functionality:
22 February 2010
   released version 0.2.172 of DoxyBlocks
I gave it a try and it looks quite good. :P

Hence I have some suggestions to make:
1.) It was hard to me to find out how I actually use this. Until I found the toolbar which gives access to the functions. An extra "doxygen" menu would be fine.
2.) In addition some of the options should go into the editors context menu, too (like "add doxygen comment at current editor position) for convenience.
3.) The "DOT_PATH" is written twice if you setup the DOT executable. You just need to remove the additional line:
Code
sText +=  _T("DOT_PATH               =\n");
4.) Having the possibility to view the HTML file in the internal HTML viewer of C::B would be really convenient, too. You can have a look how it's done in the build log.
5.) The project file needs some clean up as there are absolute path's included that make installation fail. You should consider to put all path's relative to the "contrib" plugin folder. That's what most people expect I'd say.
6.) The setup dialog is quite huge and although I personally don't really care I think users with small screen resolutions will complain sooner or later.

Besides this I just started using it and having fun. :)
Compiler logging: Settings->Compiler & Debugger->tab "Other"->Compiler logging="Full command line"
C::B Manual: https://www.codeblocks.org/docs/main_codeblocks_en.html
C::B FAQ: https://wiki.codeblocks.org/index.php?title=FAQ

Offline Cryogen

  • Regular
  • ***
  • Posts: 260
Re: Doxygen plugin
« Reply #14 on: February 25, 2010, 09:31:18 pm »

 Hi Guys,

Thanks for all of the discussion and feedback, much appreciated. Thanks, Morten, for the detailed response. I'll respond to that separately.

I have just uploaded V0.2.178. Changes since 172:

-Updated: Documentation.
-Fixed: Prefs dlg order and improved the layout slightly.
-Added: Warning checkbox toggles other warnings which I forgot to add before.
-Updated: The entire project to run from \src\plugins\contrib\. Hopefully that will solve some problems.

Note in particular that last, which speaks to one of Morten's comments.

Now then, I spent, or rather lost, an entire day (more like 16 hrs than 8!) trying to get the thing to run under Ubuntu and have ended up very frustrated. Firstly, the SVN version I built just won't run. It just hangs without output, even on the command line. I then spent hoooooooooooooours chasing down the solution to this error:

Quote
codeblocks: relocation error: /usr/lib/libcodeblocks.so.0: symbol _Z18wxSafeConvertWX2MBPKw, version WXU_2.8.2 not defined in file libwx_baseu-2.8.so.0 with link time reference

I have tried every solution that I could find, every package, repository, custom build, you name it. Nothing works and it then took me more hours to recover to 8.02. The only good that came from it is that I seem to have acquired a later version of wxSmith in the process which now has the Extra Code field that was stopping me before.

OK, so now I can build DoxyBlocks but will it run? No way. Not for anything. More wasted hours. It seems, from a comment of Jens', that there is an inherent problem with third-party plug-ins that causes the correct paths to be lost during start-up and therefore the thing fails looking for plug-in zip files. To say that I'm not impressed is an understatement.  :?

Result: I give up. I can build it and will post a version for others to try shortly but it seems that it won't run properly until such time as it's pre-built and supplied with C::B. That's just terrible. If anyone that knows more about this can help, that'd be great but it seems terminal thus far.

On to the good news. It installs and behaves as expected for me. There's a .cbplugin available now that was built from the C::B \src\ tree. I hope that that will remove some issues experienced by others. I have replaced the $(#CB) env. var., which I'm sure was provided by the project wizard, and used relative paths to be consistent with other plug-ins. It now only uses $(#WX), which should be standard with one exception. I have been unable to find any way to build wx with the "$(#WX.lib)\gcc_dll$" style path. After much searching, the only method I could get to work was creating my own dirs within the wx tree for each build, so I have this style of thing:

...\wxWidgets-2.8.10\msw-release-mono\lib\...

so the one path that I think you'll have to change is this one:

$(#wx.lib)\wx\include\msw-unicode-release-2.8

to this, I think:

$(#WX.lib)\gcc_dll$(WX_CFG)\msw$(WX_SUFFIX)

Again, if anyone would care to educate me on how to achieve the paths that C::B expects by default, that wold be good as I currently have to edit every instance which, you might say, is sub-optimal.  :)

Here's a new snapshot:


and, finally, the docs are now online at:

http://doxyblocks.sourceforge.net/

Cheers,

  Cryo.