☰

解释 Latex 中的函数调用（语法）

tag-icon • tag-icon packages documentation syntax
解释 Latex 中的函数调用（语法）

我有一个带有公共 API 的软件产品，我想用 LaTeX 来记录它。输出应如下所示

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

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

我目前使用列表作为第一行并使用描述环境作为参数解释来实现这一点。

有没有一个包可以让我写类似的东西

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

我尝试自己开发它，但它停留在将 CallString 写入 aux 文件，因为我将函数环境作为描述环境处理，并希望在第二次运行中从 aux 文件加载第一行。

所以问题是，是否已经有一个可以实现这一点的软件包。

答案1

有几种语言提供了从源代码中正确格式化的注释中提取函数签名和其他文档字符串的功能。还有 doxygen 程序（http://www.doxygen.nl/)，它支持几种编程语言，这些语言本身可能不提供 LaTeX 文档支持，并且显然可以适应其他语言，以防你的语言不在列表中。如果你使用这样的功能，你可以

  1. 将文档和源代码放在一起，这样当代码发生更改时，更容易保持文档的更新，

  2. 从同一源生成离线（LaTeX）和在线（HTML）文档。

我建议您探索一下这种方法。

答案2

您可以处理 (La)TeX 内的所有内容。

以下最小示例对function环境进行两次处理。在第一个循环中，它捕获所有 s\param以隔离它们type以及它们是否是required（键）。对环境的第二次处理使用隔离的键\param在description环境中设置 s。您也可以为每个参数定义一个新的name。扩展也是可能的。

在此处输入图片描述

\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}

相关内容