I am currently documenting a F95/2003 software project with the help of doxygen. On the one hand I grouped corresponding pages with the help of #defgroup, #addtogroup, #ingroup.... which end up under the point Modules in the table of contents and the top menu. Then the project also contains Fortran Modules, properly documented, and they appear also as a separate Modules point in the table of contents, which makes them hard to distinguish. How can I rename one of them? Like naming the Module pages generated from the Fortran modules' documentation as Fortran Modules or the best option would be to get completely rid of the separate Modules pages for the Fortran modules, since they also belong to a doxygen group and can be found there asl well?
In principle the "Fortran modules" are listed as namespaces, but by means of the OPTIMIZE_FOR_FORTRAN = YES the name is changed into "Modules". To get the correct naming is of course a difficult problem.
Doxygen has also the possibility to change, in respect to names and showing / hiding) some layout elements, see the doxygen manual paragraph: "Changing the layout of pages" (http://doxygen.nl/manual/customize.html#layout).
when creating a layout file say:
doxygen -l mylayout.xml
and changing here the line (approximately line 8):
<tab type="namespaces" visible="yes" title="">
into
<tab type="namespaces" visible="yes" title="Fortran Modules">
and setting in the doxygen configuration file (Doxyfile):
LAYOUT_FILE = mylayout.xml
I think you get the effect you want to have.
The following I didn't try (so I don't know what the effect might be in your case, and I have big doubts but I mentioned it here for completeness as it came into my mind), but doxygen has also the \namespace command maybe you can use this in this case in stead of the grouping commands.
I'm working on a C++ project and really fell in love with the Sphinx documentation build system. I managed to setup Doxygen and Breathe to produce and provide the C++ descriptions to Sphinx.
I can't figure out how Google's Ceres Solver documentation was done. Their API reference for example contains class names followed by lots of text, sometimes even with code block examples as shown in the previous link. Is there a way to write Doxygen documentation inside the source files and achieve this?
Another example is this class documentation, which has around two pages of text. I somehow doubt that all this text is located in the source files as Doxygen comments. I have the feeling that all the extra text has been written in the restructured text sources for the documentation and nothing in the c++ source files. But then what is the point of using doxygen and breathe...
Or asked differently, where should I put high-level information about the code? I mean I can document class1 and class2 in their sources, but somewhere I need to explain how both of them interact and are used together. This is what the documentation of the Ceres Solver does so nicely in my opinion.
Alternatively you could point me to a C++ project with the Sphinx + Doxygen + Breathe pipeline and open source documentation. Then I can see for myself how to do these things. Unfortunately I don't know about any project.
I missed the github link for the Ceres Solver. There the sources of the documentation can be found. I'm a bit disappointed, because the complete documentation is written in the Restructured Text source files and NOT inside the c++ code. Basically they reference the class name with .. class:: className and then add ReST markdown for informative text, example code blocks etc. One example is given in "Modeling Non-linear Least Squares"
Recently, I changed the output path of my project (a class library) from the default (../bin/debug) to:
$(OURDIRECTORY_BUILD)\Debug\
where OURDIRECTORY is an environmental (System) variable).
I also changed the UnitTest project (that was in the same solution) to reference the class library like this:
Reference Include="MyLibrary">
$(OURDIRECTORY )\Debug\MyLibrary.dll
Previously, I had just referenced it as a project reference. I made the change from project reference to the above as I was having build problems once I changed the Output Path.
Anyhow, now all is building and the unit tests are all passing BUT when I look at the NCrunch metrics, they are all at 0.00% AND the code coverage markers are all white (no coverage). Obviously, I do have coverage (very close to 100%) and something about changing the output path has confused NCRUNCH. How should I be handling this?
I am somewhat constrained to use this idea of a environmental variable for the output path as my boss is suggesting it. We have multiple libraries being built (not all in same solution) and are trying to make everything build-able on multiple machines. This scheme lets each engineer pick his own path for the environmental variable and even have a couple of code bases that he can switch between by changing the environment variable value.
Let me know if I can provide more details or if there is a more appropriate place to post.
Thanks,
Dave
I got no comments/answers here, perhaps this question was too product specific for StacKOverflow. My apologies. After I posted here, I came across a dedicated NCrunch forum site and posted there. I got some useful info. So for those of you looking deparately looking for an answer (as I was) I refer you to:
http://forum.ncrunch.net/yaf_postsm5457_NCRUNCH-code-coverage-markers-are-all-white-after-changing-output-path-of-project-under-test.aspx#post5457
If that link doesn't work in the distant future, search for the title,
"NCRUNCH code coverage markers are all white after changing output path of project under test", and if that doesn't work, the brief (and most important part of) answer is to use two paths like so:
<OutputPath Condition="'$(NCrunch)' == '1'">bin\</OutputPath>
<OutputPath Condition="'$(NCrunch)' != '1'">$(OUTDIRECTORY)</OutputPath>
This worked for me.
Dave
I just started to use doxygen and may not be familiar with all available settings. I looked into all tags and options in configuration file, but havent been able to locate any relevant tag for the operation.
Is there any way to force doxygen to index externals in C/C++ ? Now they just plainly added to list of other variables in the source file.
EDIT: From what I have seen so far, is that doxygen doesnt understand the externals at all. It generates a references in html files for these variables or functions to random ( first seen ) locations
Local variables with file-only scope are marked as static, right? So when setting EXTRACT_STATIC to NO you won't see them at all.
That said: there is now no clear distinction between static and external variables in the index. I have plans to redesign the indexes to make them more interactive and then I will take your wish along (i.e. be able to filter on static v.s. external). If you want to be notified on when this happens please file a bug report with severity set to enhancement in doxygen's bug tracker.
I was going to create the C++ IDE Vim extendable plugin. It is not a problem to make one which will satisfy my own needs.
This plugin was going to work with workspaces, projects and its dependencies.
This is for unix like system with gcc as c++ compiler.
So my question is what is the most important things you'd need from an IDE? Please take in account that this is Vim, where almost all, almost, is possible.
Several questions:
How often do you manage different workspaces with projects inside them and their relationships between them? What is the most annoying things in this process.
Is is necessary to recreate "project" from the Makefile?
Thanks.
Reason to create this plugin:
With a bunch of plugins and self written ones we can simulate most of things. It is ok when we work on a one big "infinitive" project.
Good when we already have a makefile or jam file. Bad when we have to create our owns, mostly by copy and paste existing.
All ctags and cscope related things have to know about list of a real project files. And we create such ones. This <project#get_list_of_files()> and many similar could be a good project api function to cooperate with an existing and the future plugins.
Cooperation with an existing makefiles can help to find out the list of the real project files and the executable name.
With plugin system inside the plugin there can be different project templates.
Above are some reasons why I will start the job. I'd like to hear your one.
There are multiple problems. Most of them are already solved by independent and generic plugins.
Regarding the definition of what is a project.
Given a set of files in a same directory, each file can be the unique file of a project -- I always have a tests/ directory where I host pet projects, or where I test the behaviour of the compiler. On the opposite, the files from a set of directories can be part of a same and very big project.
In the end, what really defines a project is a (leaf) "makefile" -- And why restrict ourselves to makefiles, what about scons, autotools, ant, (b)jam, aap? And BTW, Sun-Makefiles or GNU-Makefiles ?
Moreover, I don't see any point in having vim know the exact files in the current project. And even so, the well known project.vim plugin already does the job. Personally I use a local_vimrc plugin (I'm maintaining one, and I've seen two others on SF). With this plugin, I just have to drop a _vimrc_local.vim file in a directory, and what is defined in it (:mappings, :functions, variables, :commands, :settings, ...) will apply to each file under the directory -- I work on a big project having a dozen of subcomponents, each component live in its own directory, has its own makefile (not even named Makefile, nor with a name of the directory)
Regarding C++ code understanding
Every time we want to do something complex (refactorings like rename-function, rename-variable, generate-switch-from-current-variable-which-is-an-enum, ...), we need vim to have an understanding of C++. Most of the existing plugins rely on ctags. Unfortunately, ctags comprehension of C++ is quite limited -- I have already written a few advanced things, but I'm often stopped by the poor information provided by ctags. cscope is no better. Eventually, I think we will have to integrate an advanced tool like elsa/pork/ionk/deshydrata/....
NB: That's where, now, I concentrate most of my efforts.
Regarding Doxygen
I don't known how difficult it is to jump to the doxygen definition associated to a current token. The first difficulty is to understand what the cursor is on (I guess omnicppcomplete has already done a lot of work in this direction). The second difficulty will be to understand how doxygen generate the page name for each symbol from the code.
Opening vim at the right line of code from a doxygen page should be simple with a greasemonkey plugin.
Regarding the debugger
There is the pyclewn project for those that run vim under linux, and with gdb as debugger. Unfortunately, it does not support other debuggers like dbx.
Responses to other requirements:
When I run or debug my compiled program, I'd like the option of having a dialog pop up which asks me for the command line parameters. It should remember the last 20 or so parameters I used for the project. I do not want to have to edit the project properties for this.
My BuildToolsWrapper plugin has a g:BTW_run_parameters option (easily overridden with project/local_vimrc solutions). Adding a mapping to ask the arguments to use is really simple. (see :h inputdialog())
work with source control system
There already exist several plugins addressing this issue. This has nothing to do with C++, and it must not be addressed by a C++ suite.
debugger
source code navigation tools (now I am using http://www.vim.org/scripts/script.php?script_id=1638 plugin and ctags)
compile lib/project/one source file from ide
navigation by files in project
work with source control system
easy acces to file changes history
rename file/variable/method functions
easy access to c++ help
easy change project settings (Makefiles, jam, etc)
fast autocomplette for paths/variables/methods/parameters
smart identation for new scopes (also it will be good thing if developer will have posibility to setup identation rules)
highlighting incorrect by code convenstion identation (tabs instead spaces, spaces after ";", spaces near "(" or ")", etc)
reformating selected block by convenstion
Things I'd like in an IDE that the ones I use don't provide:
When I run or debug my compiled program, I'd like the option of having a dialog pop up which asks me for the command line parameters. It should remember the last 20 or so parameters I used for the project. I do not want to have to edit the project properties for this.
A "Tools" menu that is configurable on a per-project basis
Ability to rejig the keyboard mappings for every possible command.
Ability to produce lists of project configurations in text form
Intelligent floating (not docked) windows for debugger etc. that pop up only when I need them, stay on top and then disappear when no longer needed.
Built-in code metrics analysis so I get a list of the most complex functions in the project and can click on them to jump to the code
Built-in support for Doxygen or similar so I can click in a Doxygen document and go directly to code. Sjould also reverse navigate from code to Doxygen.
No doubt someone will now say Eclipse can do this or that, but it's too slow and bloated for me.
Adding to Neil's answer:
integration with gdb as in emacs. I know of clewn, but I don't like that I have to restart vim to restart the debugger. With clewn, vim is integrated into the debugger, but not the other way around.
Not sure if you are developing on Windows, but if you are I suggest you check out Viemu. It is a pretty good VIM extension for Visual Studio. I really like Visual Studio as an IDE (although I still think VC6 is hard to beat), so a Vim extension for VS was perfect for me. Features that I would prefer worked better in a Vim IDE are:
The Macro Recording is a bit error prone, especially with indentation. I find I can easily and often record macros in Vim while I am editing code (eg. taking an enum defn from a header and cranking out a corresponding switch statement), but found that Viemu is a bit flakey in that deptartment.
The VIM code completion picks up words in the current buffer where Viemu hooks into the VS code completion stuff. This means if I have just created a method name and I want to ctrl ] to auto complete, Vim will pick it up, but Viemu won't.
For me, it's just down to the necessities
nice integration with ctags, so you can do jump to definition
intelligent completion, that also give you the function prototype
easy way to switch between code and headers
interactive debugging with breaakpoints, but maybe
maybe folding
extra bonus points for refactoring tools like rename or extract method
I'd say stay away from defining projects - just treat the entire file branch as part of the "project" and let users have a settings file to override that default
99% of the difference in speed I see between IDE and vim users is code lookup and navigation. You need to be able to grep your source tree for a phrase (or intelligently look for the right symbol using ctags), show all the hits, and switch to that file in like two or three keystrokes.
All the other crap like repository navigation or interactive debugging is nice, but there are other ways to solve those problems. I'd say drop the interactive debugging even. Just focus on what makes IDEs good editors - have a "big picture" view of your project, instead of single file.
In fact, are there any plugins for vim that already achieve this?