References to LaTeX equations using Doxygen - c

I am currently documenting some advanced simulation tools using Doxygen. I would like to be able to refer to equations within the HTML documentation.
To illustrate the problem. Perform the following
doxygen -g Doxyfile
sed -i 's/^EXTRA_PACKAGES.*/EXTRA_PACKAGES = amsmath amsfonts/g' Doxyfile
sed -i 's/^LATEX_BATCHMODE.*/LATEX_BATCHMODE = YES/g' Doxyfile
You now have a Doxyfile, which can be used for a project containing formulas.
In the same directory put the following
sample.h:
/**
* #file sample.h
*/
/**
* #mainpage Some example
*
* Some complicated math:
* \f{equation}{\label{eq:1}
* p(\vec{r}_{0},t) = \ldots
* \f}
*/
/**
* The function computes the pressure based on \f$\ref{eq:1}\f$
*
* #param rho
* #param v
* #param r
* #param t
*
* #return
*/
int CalcPressure(float rho, float v[3], float r[3], float t);
Execute the following to generate LaTeX documentation.
doxygen Doxyfile
cd latex
make
A reference to equation (1.1) is put in the documentation for the CalcPressure function.
The HTML documentation on the other hand contains a '??' reference to the formula. Is it possible to tweak doxygen to run twice for the generation of formulas, such that the image created contains the reference '(1.1)' rather than '??'.
Another solution may also work. I know how to include references to functions in another LaTeX document by using the xr package, http://www.cheshirekow.com/wordpress/?p=335
I could use this procedure, if I could tell Doxygen to not delete the _formulas.aux file, rename the file and pass this as input using the xr package, but I have no idea of how to tell Doxygen not to delete temporary files.
I hope there is a solution for creating references to formulas. Help please

A partial answer. To remove the ?? from html, make the link only in latex
/**
* The function computes the pressure based on #latexonly\ref{eq:1}#endlatexonly
*/
But this way you won't get a link in html.

I managed to find a solution myself.
I created a script
Linux: latex2
#!/bin/bash
if [ $# -lt 1]; then
echo $0: usage: latex2 args
exit 1
fi
latex $*
latex $*
Windows: latex2.bat
#echo off
call latex %*
call latex %*
and changed the LATEX_CMD_NAME in Doxyfile to execute this script or actually use a definition set by CMake
Doxyfile.in
LATEX_CMD_NAME = #LATEX_CMD_NAME#
CMakeLists.txt
if (UNIX OR CYGWIN)
set( LATEX_CMD_NAME "${PROJECT_SOURCE_DIR}/bin/latex2")
else()
set( LATEX_CMD_NAME "${PROJECT_SOURCE_DIR}/bin/latex2.bat")
endif()

Related

CMake finds fftw library but cannot link

I have problem linking the fftw library using cmake. I use a findFFTW.cmake file in order to find the library. I know this is successfully finding the library because I set the REQUIRED flag to be true for finding the library and the make process goes through fine.
Despite linking it with my executable, I am still getting undefined reference errors. Some related posts, whose solutions I have tried.
Undefined reference to "function name from external library"
http://answers.ros.org/question/171326/catkin-linking-order-undefined-reference-to-symbol/
Updates
Thanks to ComicSansMS, the CMake below should now model the dependencies correctly.
CMake file of project (updated 3/7)
cmake_minimum_required(VERSION 2.8.3)
project(gist_extractor)
## Find catkin macros and libraries
find_package(catkin REQUIRED COMPONENTS
roscpp
rospy
std_msgs
image_transport
cv_bridge
sensor_msgs
cmake_modules
)
find_package(OpenCV REQUIRED)
find_package(Eigen REQUIRED)
find_package(FFTW REQUIRED)
###########
## Build ##
###########
## Set GIST variables for building library
set(GIST_PATH /home/andy/Development/lear_gist-1.2)
## Specify additional locations of header files
include_directories(include ${catkin_INCLUDE_DIRS} ${GIST_PATH} ${FFTW_INCLUDES})
## Declare a gist library
add_library(gist SHARED ${GIST_PATH}/standalone_image.c ${GIST_PATH}/gist.c) # THIS IS NOT BEING BUILT
target_link_libraries(gist ${FFTW_LIBRARIES})
## Add cmake target dependencies of the library
#MESSAGE( STATUS "GIST_LIBRARY_PATH: " ${GIST_PATH})
## Declare a C++ executable
add_executable(gist_extractor src/gist_extractor.cpp)
target_link_libraries(gist_extractor ${catkin_LIBRARIES} gist)
EDITS 2
We now have a linking error if we use the above CMake file. Specifically the make process fails when I try running
target_link_libraries(gist_extractor ${catkin_LIBRARIES} gist)
I have a couple of observations. Firstly, my gist library is being built correctly based on the below console messages.
Linking C shared library /home/andy/Projects/ROS/robot_ws/devel/lib/libgist.so
[ 80%] Built target gist
Scanning dependencies of target gist_extractor
[100%] Building CXX object
`gist_extractor/CMakeFiles/gist_extractor.dir/src/gist_extractor.cpp.o
But we can see that there are undefined reference errors when we try to link our executable with the gist library.
Linking CXX executable gist_extractor
: undefined reference to `color_gist_scaletab'
Here's why I don't understand why this is occurring. In gist_extractor.cpp, I have included the header file that includes the 'color_gist_scaletab' function. Specifically, this 'color_gist_scaletab is in defined in 'gist.h' and implemented in 'gist.c'. I would think that building my library gist should give me access to 'color_gist_scaletab'. I have posted the relevant files below.
gist.h
#ifndef GIST_H_INCLUDED
#define GIST_H_INCLUDED
#include "standalone_image.h"
/*! Graylevel GIST for various scales. Based on Torralba's Matlab
* implementation. http://people.csail.mit.edu/torralba/code/spatialenvelope/
*
* Descriptor size is w*w*sum(n_orientations[i],i=0..n_scale-1)
*
* #param src Source image
* #param w Number of bins in x and y axis
*/
float *bw_gist_scaletab(image_t *src, int nblocks, int n_scale, const int *n_orientations);
/*! #brief implementation of grayscale GIST descriptor.
* Descriptor size is w*w*(a+b+c)
*
* #param src Source image
* #param w Number of bins in x and y axis
*/
float *bw_gist(image_t *scr, int nblocks, int a, int b, int c);
/*! #brief implementation of color GIST descriptor.
*
* #param src Source image
* #param w Number of bins in x and y axis
*/
float *color_gist(color_image_t *src, int nblocks, int a, int b, int c);
/*! Color GIST for various scales. Based on Torralba's Matlab
* implementation. http://people.csail.mit.edu/torralba/code/spatialenvelope/ */
float *color_gist_scaletab(color_image_t *src, int nblocks, int n_scale, const int *n_orientations);
#endif
gist_extractor.cpp
// color_gist_scaletab is defined in gist.h
// I'm including relevant header file
#include "/home/andy/Development/lear_gist-1.2/gist.h"
//SOME MORE STUFF
// This is where I call the function
float *gist_descriptor = color_gist_scaletab(im, nblocks, n_scale, orientations_per_scale);
It seems you did not model your dependencies correctly.
You use fftw from inside gist.c, which is part of the gist library target.
However, that target does not have a dependency to fftw, only the downstream target gist_extractor has. This is a recipe for trouble, especially in static builds, where toolchains are often picky about the order in which libraries appear on the linker command line.
Add fftw as a dependency to gist:
target_link_libraries(gist ${FFTW_LIBRARIES})
Also, there is no need to do this:
add_dependencies(gist_extractor gist)
target_link_libraries(gist_extractor ${GIST_PATH}/libleargist.a)
If both targets are built as part of the same project, simply do:
target_link_libraries(gist_extractor gist)
By using the target name instead of hardcoding the output file, you not only make your build script more portable, but also allow CMake to better track the inter-target dependencies for you.

Doxygen treats main.c differently from other files

The header comments in my main.c are not being processed by doxygen, however if I rename the file from main.c to for example mainn.c it works very well.
Why is main.c treated differently from an other file name?
How do I make Doxygen manage main.c as other .c files?
Or alternatively, what is the best practice here? My purpose in Main.c is to put a short (maybe not so short) product description and use cases in the header documentation.
The header file starts as such:
/**********************************************************//**
* #file main.c
* #author Somebody
* #brief Main function and support functions.
* #details
Then continues with application level things I want to document.
Doxygen configuration is the default as it is installed, except for a few items, such as optimised for C, include call charts etc...
Thanks..
Kinda hard to tell without seeing how you've tried to document it... But make sure you have a line in the main.c file that reads
/*! file */
or
/** #file */
(Doxygen doesn't document global objects by default)
After mucking around a bit here is the solution. (As proposed by MPI_What.
As mentioned in my question
/**********************************************************//**
* #file main.c
* #author Somebody
* #brief Main function and support functions.
* #details
Works for all files except main.c (Of course the line #file main.c is different for the other files. However the following works well for main.c also:
/**********************************************************//**
* #file
* #author Somebody
* #brief Main function and support functions.
* #details
Why it works is a mystery, but it does.
Thanks, Adrian

How do I print my functions doc strings with doxygen?

I'm using doxygen to document some C code. I have doxygen friendly comments:
/**
* some comment
*
* #param a something
*/
and my directory structure looks like this:
libproject/
src/
project.h
project.c
docs/
project.doc.conf
index.txt
Makefile
I have generated project.doc.conf with doxygen -g project.doc.conf and configured the INPUT tag to be
INPUT = index.txt ../src/
I've also added a dummy index.txt:
/*! \mainpage My Personal Index Page
*
* \section intro_sec Introduction
*
* This is the introduction.
*
* \section install_sec Installation
*
* \subsection step1 Step 1: Opening the box
*
* etc...
*/
for testing. When I run:
$ doxygen project.doc.conf
I get two new folders in libproject/docs/: html and latex. So far, so good.
However when I navigate to index.html in my browser I just get the index page and a list of files. I can browse the source but the documentation is missing!
Where is the documentation? Do I have to specify some tags for doxygen to draw it?
You must document each file using:
/**
* #file project.h
* #brief some brief description
*/
http://www.doxygen.nl/manual/docblocks.html#structuralcommands

Doxygen problems with paths in \file command

I've got the following problem using Doxygen 1.7.x: I document various files in a subdirectory and they are referred with different filename styles, both with and without their path, on the corresponding Modules page. But I want to have relative paths (w.r.t. the project root) on the modules page.
The two files are tagged as follows:
/**
* #addtogroup examples_itsolver
* #{
* #file example/itsolver/bicgstab_1.c
* #brief Demostrate the usage of BiCGStab
* #date 05/21/2012
* #version $Id$
*#}
*/
and
/**
* #addtogroup examples_itsolver
* #{
* #file example/itsolver/sor.c
* #brief Demostrate the usage of SOR
* #date 05/21/2012
* #version $Id$
*#}
*/
This results in
file bicgstab_1.c
Demonsrate the usage of BiCGStab.
file example/itsolver/sor.c
Demonstrate the usage of the SOR Iterative Solver.
on the Module overview page. But I want to have all files documented like sor.c across the whole project. How can I achieve this? Using the FULL_PATH_NAMES configuration option does not help.
A full example (including the generated html output) is available on http://www-e.uni-magdeburg.de/makoehle/doxygen_error.tgz
The problem is that in your example there are two files called sor.c
example/itsolver/sor.c
lib/itsolver/sor.c
doxygen will prepend as much of the path as needed to make the name unique.
If example contains usage examples, then it is better not to include these in the input, but use #snippet, #include, or #example instead and point EXAMPLE_PATH to your example directory.

Non-standard special documentation blocks and doxygen

I'm using a 3rd party API C sources where special documentation blocks are as following
/****************************************************************************************
* #fn fn
*
* #brief brief
*
* #param param
*
* #return return
****************************************************************************************
*/
void fn(void)
{
...
}
Is there a way to convince Doxygen these are real special documentation blocks without modifying sources in order to match standard block (e.g. exactly two asterisks at block start)?
Thank you in advance.
I suggest to create an input filter that replaces /****** by /** and add that to the INPUT_FILTER
option in the configuration file. If you have the Unix command sed on your system, the following would do the trick:
INPUT_FILTER = "sed -e 's|/\*\*\**|/**|g'"

Resources