[BC BREAK] _todo_: No value by default and output warning

* base.xml (_todo): Do not output a value by default.  Output warning with
  `@desc@'.
  [@hide@]: Remove parameter.
  [@value@, @index@]: Add parameters.
master
Mike Gerwitz 2018-01-25 16:16:34 -05:00
parent b3117e7c55
commit c2f074f269
1 changed files with 24 additions and 13 deletions

View File

@ -135,14 +135,12 @@
<section title="Work-In-Progress"> <section title="Work-In-Progress">
The templates in this section handle code that is \ref{_todo_} formalizes TODO items and may optionally yield a
a~work-in-progress; they should probably not be used in production value~\tt{@value@} for use within calculations.%
code, since they indicate that something is incomplete or unused. \footnote{This is different than its previous behavior of always
yielding a scalar~$0$.}
\ref{_todo_} formalizes TODO items and \may~always yield a scalar All uses of the \ref{_todo_} template will produce a warning composed of
integer~0, so it may be used within calculations. If yielding a its description~\tt{@desc@}.
constant value is not appropriate, it \may~also be stripped from
the output entirely.
<template name="_todo_" <template name="_todo_"
desc="Represents work that needs to be done"> desc="Represents work that needs to be done">
@ -150,13 +148,26 @@
<text>TODO</text> <text>TODO</text>
</param> </param>
<param name="@hide@" desc="Whether to hide content by stripping <param name="@value@" desc="Placeholder value" />
it entriely from the output" /> <param name="@index@" desc="Placeholder value index">
<text></text>
</param>
<unless name="@hide@"> <unless name="@value@">
<c:const value="0" <unless name="@index@" eq="">
desc="TODO: {@desc@}" /> <error>Using @index@ without @value@</error>
</unless>
</unless> </unless>
<warning>
TODO: <param-value name="@desc@" />
</warning>
<if name="@value@">
<c:value-of name="@value@" index="@index@" />
</if>
</template> </template>