Explaining function calls in latex (syntax)

Question

I have a software product with an public api, which i want to documentate in LaTeX. The output should look like the following

FunctionName(type1 param1, type2 param2 [, type3 param3] ...)

param1: (required) does this
param2: (required) does this with an longer explanation
param3: does that

I currently achive that with lstlistings for the first line and an description Environment for the paramter explanation.

Is there a package that allows me to write something like

\begin{function}{<functionName>}
    \param[type=type1,required] does this
    \param[type=type2,required] does that
    ...
\end{function}

I tried to develop that by myselve but it stuck at writing the CallString to the aux file, because i processed the function environment as an description environment, and wanted to load the first line in the second run from an aux file.

So the question is, whether there is allready a package that can archieve that.

score 2 · Answer 1 · answered Oct 17 '18 at 05:17

You can process all of the content within (La)TeX.

The following minimal example processes the function environment twice. In the first cycle it captures all the \params to isolate their type and whether they're required (keys). The second processing of the environment sets the \params in a description environment using the isolated keys. You can define a new name for each parameter as well. Extensions are also possible.

\documentclass{article}

\usepackage{environ,xkeyval,multido}

% Setup keys used in \param[<keys>]
\makeatletter
% Key: type (defaults to <blank>)
\define@cmdkey{params}[@param@]{type}[]{%
  \expandafter\xdef\csname param@\FunctionName @\theparamcount @type\endcsname
    {\@param@type}}
% Key: required (defaults to true)
\define@cmdkey{params}[@param@]{required}[true]{%
  \expandafter\xdef\csname param@\FunctionName @\theparamcount @required\endcsname
    {\@param@required}}
% Key: name (defaults to param#)
\define@cmdkey{params}[@param@]{name}[param\theparamcount]{%
  \expandafter\xdef\csname param@\FunctionName @\theparamcount @name\endcsname
    {\@param@name}}

\newcommand{\setparam}{\global\@namedef{param@\theparamcount}}
\newcounter{paramcount}
\NewEnviron{function}[1]{%
  \def\FunctionName{#1}% Capture function name
  \setcounter{paramcount}{0}%
  \newcommand{\param}[1][]{%
    \stepcounter{paramcount}% Count parameters
    \setkeys{params}{%
      type, % Default type is empty
      name,% Default name is param#
      ##1}% Local specifications
  }%
  \setbox1=\hbox{\BODY}% process \BODY once to pick up parameters
  \par
  \noindent
  \def\paramsep{\def\paramsep{, }}% https://tex.stackexchange.com/a/89187/5764
  \textbf{#1}% Set function name
  (\multido{\i=1+1}{\value{paramcount}}{% Set parameters
    \paramsep
    \csname param@\FunctionName @\i @type\endcsname~% Type
    \csname param@\FunctionName @\i @name\endcsname% Name
    }%
  )
  \par
  % Set parameters using a description environment
  \begin{description}
    \setcounter{paramcount}{0}%
    \renewcommand{\param}[1][]{%
      \stepcounter{paramcount}%
      \item[\csname param@\FunctionName @\theparamcount @name\endcsname:]
      \ifnum\pdfstrcmp{\csname param@\FunctionName @\theparamcount @required\endcsname}{true}=0
        (required)% Item is required
      \fi
    }
    \BODY
  \end{description}
}

\makeatother

\begin{document}

\begin{function}{functionNameA}
  \param[type = typeA, name = stringA] does this
  \param[type = typeB, required] does that
  \ldots
\end{function}

\bigskip

\begin{function}{functionNameB}
  \param[type = typeC, name = somethingA] does this
  \param[type = typeB, name = somethingB, required] does that
  \ldots
\end{function}

\bigskip

\begin{function}{functionNameC}
  \param[type = typeD, required] does this
  \param[type = typeE, required] does that
  \ldots
\end{function}

\end{document}

score 0 · Accepted Answer · edited Dec 26 '18 at 16:58

Several languages provide facilities for extracting function signatures and other documentation strings from properly formatted comments in the source code. There is also the doxygen program (http://www.doxygen.nl/), which supports several programming languages that may not provide LaTeX documentation support themselves, and which can apparently be adapted to additional languages, in case yours is not already on the list. If you used such a facility, you could

keep the documentation and the source code together, which makes it easier to keep the docs up to date when the code changes,
generate both offline (LaTeX) and online (HTML) docs from the same source.

I would suggest that you explore this approach.

Explaining function calls in latex (syntax)

2 Answers2