0

I have a C project that I am documenting in latex. It features doxygen comments (like those /** bla */ /**< blab */ /// bla blub ///< blubber). I use the listings package to include parts of the code into my documentation. Is there any way I can have the doxygen code in my C-Code, have \lstinputlisting handle the imports and have it remove the doxygen comments with normal comments (// fizz /* buzz */) still in place (note that the \inputCCode and \inputCCodeRanges commands are selfdefined but provide glorified \lstinputlisting commands)? I would be ok with using some sort of preprocessing tool as well but if it would be possible to have the listings package do the whole work in one go it would be prefered...

Consider this my MWE:

%file main.tex
\documentclass[a4paper,10pt]{report}

\usepackage[english,ngerman]{babel}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc} 
\usepackage{listings}
\usepackage{ifthen} 
\usepackage{xstring}
\usepackage{xcolor}

\input{programmingLanguagesFormating}

\begin{document}
\section{some title}
Some text that refers some code included with explicit line numbers 
\inputCCode{1}{3}{some code to be refered to }{code.h}
Some text that refers some code that is included with the ranged include (solutions shall work with this as well)
\inputCCodeRanges{1-2,5-5,7-7}{Ranges of code that will explain the world}{code.h}
\end{document}

I outsourced the style definition of the programming language (C in my case) for obvious reasons (hint: length).

%file programmingLanguagesFormating.tex
\definecolor{CComment}{rgb}{0.13,0.545,0.13}
\definecolor{CKeyword}{rgb}{0,0,1}
\definecolor{CString}{rgb}{0.627,0.125,0.941}
\lstdefinestyle{Cstyle}
{
    language=C,
    tabsize=4,
    basicstyle=\ttfamily,
    columns=flexible,
    breaklines=true,
    numbers=left,
    showstringspaces=true,
    rulecolor=\color{black},
    numberstyle=\tiny\color{black},
    stringstyle=\color{CString},
    keywordstyle=\bfseries\color{CKeyword},
    commentstyle=\itshape\color{CComment},
    frame=line,
    title=\lstname,
    captionpos=b,
}
\lstnewenvironment{C}
  {\lstset{ language=C, style=CStyle}}
  {}

\newcommand{\inputCCode[5]}{\lstinputlisting[language=C,style=Cstyle,firstline=#2, lastline=#3,firstnumber=#2, caption={[#4]#4\hfill\\({\ifthenelse{\equal{#2}{#3}}{Line #2}{Lines #2~--~#3}} in File #5)}]{#5}}

\makeatletter % taken from https://tex.stackexchange.com/questions/110187/listings-line-numbers-that-match-the-linerange-specification
\makeatletter
\def\lst@MSkipToFirst{%
    \global\advance\lst@lineno\@ne
    \ifnum \lst@lineno=\lst@firstline
        \def\lst@next{\lst@LeaveMode \global\lst@newlines\z@
        \lst@OnceAtEOL \global\let\lst@OnceAtEOL\@empty
        \ifnum \c@lstnumber>0
            \vspace{2 mm}
        \fi
        \lst@InitLstNumber % Added to work with modified \lsthk@PreInit.
        \lsthk@InitVarsBOL
        \c@lstnumber=\numexpr-1+\lst@lineno % this enforces the displayed line numbers to always be the input line numbers
        \lst@BOLGobble}%
        \expandafter\lst@next
    \fi}
\makeatother

\newcommand{\inputCCodeRanges[4]}{\lstinputlisting[language=C,style=Cstyle,linerange={#2}, caption={[#3]#3\hfill\\({\IfSubStr{#2}{,}{Lineranges #2}{Linerange #2}} in File #4)}]{#4}}

Lastly let the file code.h be:

// some C-Programming includes (this is a comment of the kind i need to keep)
#include <stdio.h>
#include <math.h>

/// \brief This is a demo function that is not even implemtented (this comment should go away (doxygen stlye))
void wizzBangGizmoAlgorithm(int magicParameter); ///< this comment explains the meaning of magicParameter and shall go away as well
int fruityWidget(void);

This compiles to : result

Bonus kudos to who ever manages to replace all commas except the last one in the ranged caption with and or any other arbitrary string.

  • Please readup on doxygen commands like \snippet / \include and \lin, /skip etc. Also of interest are the settings INLINE_SOURCES, SOURCE_BROWSER, STRIP_CODE_COMMENTS and LATEX_SOURCE_CODE. Maybe you can do everything what you want in doxygen itself. – albert Jun 08 '20 at 13:56
  • Sometimes the documentation doxygen creates is just not enough (it is hard to use it to explain intentions behind code for example) so tradiditonal handwritten latex with just some snippets of code is the way to go no way around... – der bender Jun 08 '20 at 13:59
  • I don't agree as the text you want to place with the code snippet can also be handled by doxygen directly / as normal C comments or in a \latexonly block. – albert Jun 08 '20 at 14:01

0 Answers0