Commit aed29880 authored by Akim Demaille's avatar Akim Demaille
Browse files

Doxygen issues.

	* doc/doc.doxy.in: Be quiet, to emphasize warnings.
	* doc/manual/vaucanson-user-manual.tex: Save trees, use a4wide.
	* doc/manual/developer.tex (Commenting Code): New.

	* include/vaucanson/xml/xml_chooser.hh: Don't use @note when it is
	not meant to appear in the documentation.
	Also, use @param and @arg more correctly.
	Lots are still needed.
	* include/vaucanson/xml/xml_converter.hh: Idem.
	* include/vaucanson/xml/xml_chooser.hxx: Idem.
	* include/vaucanson/xml/xml_converter.hxx: Idem.
	* include/vaucanson/xml/xerces_parser.hh: Idem.
	* include/vaucanson/xml/tools.hxx: Idem.
	* include/vaucanson/contexts/ratseries_semiring.thh: Idem.
	* include/vaucanson/contexts/r_semiring.thh: Idem.
	* include/vaucanson/contexts/automaton_functions.thh: Idem.
	* include/vaucanson/contexts/transducer_functions.thh: Idem.
	* include/vaucanson/contexts/fmp_transducer_functions.thh: Idem.
	* include/vaucanson/contexts/z_semiring.thh: Idem.
	* include/vaucanson/contexts/polynom_series.thh: Idem.
	* include/vaucanson/contexts/automaton_functions.thxx: Idem.
	* include/vaucanson/contexts/automaton.thh: Idem.
	* include/vaucanson/contexts/transducer.thh: Idem.
	* include/vaucanson/contexts/transducer_functions.thxx: Idem.
	* include/vaucanson/contexts/fmp_transducer_functions.thxx: Idem.
	* include/vaucanson/contexts/boolean_semiring.thh: Idem.
	* include/vaucanson/contexts/z_min_plus_semiring.thh: Idem.
	* include/vaucanson/contexts/z_max_plus_semiring.thh: Idem.
	* include/vaucanson/contexts/generic_automaton_impl.thh: Idem.
	* include/vaucanson/contexts/dynamic_alphabet.thh: Idem.
	* include/vaucanson/contexts/generic_series.thh: Idem.
	* include/vaucanson/contexts/free_monoid_product.thh: Idem.
	* include/vaucanson/contexts/free_monoid.thh: Idem.
	* include/vaucanson/contexts/char_letter.thh: Idem.
	* include/vaucanson/algorithms/cut_up.hh: Idem.
	* include/vaucanson/automata/implementation/automaton_view.hh: Idem.
parent 7a649359
2006-06-22 Akim Demaille <akim@lrde.epita.fr>
Doxygen issues.
* doc/doc.doxy.in: Be quiet, to emphasize warnings.
* doc/manual/vaucanson-user-manual.tex: Save trees, use a4wide.
* doc/manual/developer.tex (Commenting Code): New.
* include/vaucanson/xml/xml_chooser.hh: Don't use @note when it is
not meant to appear in the documentation.
Also, use @param and @arg more correctly.
Lots are still needed.
* include/vaucanson/xml/xml_converter.hh: Idem.
* include/vaucanson/xml/xml_chooser.hxx: Idem.
* include/vaucanson/xml/xml_converter.hxx: Idem.
* include/vaucanson/xml/xerces_parser.hh: Idem.
* include/vaucanson/xml/tools.hxx: Idem.
* include/vaucanson/contexts/ratseries_semiring.thh: Idem.
* include/vaucanson/contexts/r_semiring.thh: Idem.
* include/vaucanson/contexts/automaton_functions.thh: Idem.
* include/vaucanson/contexts/transducer_functions.thh: Idem.
* include/vaucanson/contexts/fmp_transducer_functions.thh: Idem.
* include/vaucanson/contexts/z_semiring.thh: Idem.
* include/vaucanson/contexts/polynom_series.thh: Idem.
* include/vaucanson/contexts/automaton_functions.thxx: Idem.
* include/vaucanson/contexts/automaton.thh: Idem.
* include/vaucanson/contexts/transducer.thh: Idem.
* include/vaucanson/contexts/transducer_functions.thxx: Idem.
* include/vaucanson/contexts/fmp_transducer_functions.thxx: Idem.
* include/vaucanson/contexts/boolean_semiring.thh: Idem.
* include/vaucanson/contexts/z_min_plus_semiring.thh: Idem.
* include/vaucanson/contexts/z_max_plus_semiring.thh: Idem.
* include/vaucanson/contexts/generic_automaton_impl.thh: Idem.
* include/vaucanson/contexts/dynamic_alphabet.thh: Idem.
* include/vaucanson/contexts/generic_series.thh: Idem.
* include/vaucanson/contexts/free_monoid_product.thh: Idem.
* include/vaucanson/contexts/free_monoid.thh: Idem.
* include/vaucanson/contexts/char_letter.thh: Idem.
* include/vaucanson/algorithms/cut_up.hh: Idem.
* include/vaucanson/automata/implementation/automaton_view.hh: Idem.
2006-06-20 Akim Demaille <akim@lrde.epita.fr>
Address #53: Complete README with a map of the tarball.
......
......@@ -51,7 +51,7 @@ SHOW_USED_FILES = NO
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
QUIET = NO
QUIET = YES
WARNINGS = YES
WARN_IF_UNDOCUMENTED = NO
WARN_IF_DOC_ERROR = YES
......
......@@ -15,23 +15,59 @@ Until this is written, please refer to
\href{http://www.lrde.epita.fr/~akim/compil/assignments.split/Coding-Style.html#Coding-Style}{Tiger's
Coding Style}.
\subsection{Commenting Code}
\label{sec:commenting-code}
Use Doxygen. Besides the usual interface description, the Doxygen
documentation must include:
\begin{itemize}
\item references to the definitions of the algorithm, e.g., a
reference to the ``Éléments de la théorie des automates'', or even
an URL to a mailing-list archive.
\item detailed description of the assumptions, or, if you wish, pre-
and post-conditions.
\item the name of the developer
\item use the \texttt{@pre} and \texttt{@post} tags liberally.
\end{itemize}
Don't try to outsmart your tool, even though it does not use the words
``param'' and ``arg'' as we do, stick to \emph{its} semantics (let
alone to generate correct documentation without warnings). This is
correct:
\begin{lstlisting}[language=C++]
/**
* Delete memory associated with a stream upon its destruction.
*
* @arg \c T Type of the pointed element.
*
* @param ev IO event.
* @param io Related stream.
* @param idx Index in the internal extensible array of a pointer to delete.
*
* @see iomanip
* @author Thomas Claveirole <thomas.claveirole@lrde.epita.fr>
*/
template <class T>
void
pword_delete(std::ios_base::event ev, std::ios_base &io, int idx);
\end{lstlisting}
while this is not:
\begin{lstlisting}[language=C++]
/** ...
* @param T Type of the pointed element.
*
* @arg ev IO event.
* @arg io Related stream.
* @arg idx Index in the internal extensible array of a pointer to delete.
* ... */
\end{lstlisting}
\subsection{Writing Algorithms}
There is a number of requirement to be met before including an
algorithms into the library:
\begin{description}
\item[Document the algorithm] Besides the usual interface description,
the Doxygen documentation must include:
\begin{itemize}
\item references to the definitions of the algorithm, e.g., a
reference to the ``Éléments de la théorie des automates'', or even
an URL to a mailing-list archive.
\item detailed description of the assumptions, or, if you wish, pre-
and post-conditions.
\item the name of the developer
\end{itemize}
\item[Document the algorithm] See \autoref{sec:commenting-code}.
\item[Comment the code] Especially if the code is a bit tricky, or
smart, or avoids nasty pitfalls, it \emph{must} be commented.
......
......@@ -2,6 +2,7 @@
\usepackage[american]{mybabel}
\usepackage[latin1]{inputenc}
\usepackage{a4wide}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{myhyperref}
......
......@@ -2,7 +2,7 @@
//
// Vaucanson, a generic library for finite state machines.
//
// Copyright (C) 2005 The Vaucanson Group.
// Copyright (C) 2005, 2006 The Vaucanson Group.
//
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License
......@@ -49,7 +49,7 @@ namespace vcsn
* @brief Transform an automaton labeled with series to an automaton
* where all labels are series with one and only one element.
*
* @comment No cut-up work is done on input and output transitions.
* @note No cut-up work is done on input and output transitions.
*
* Works on all automata and transducers labeled with polynomial series,
* and on automata labeled with rational series.
......@@ -67,7 +67,7 @@ namespace vcsn
* @brief Transform an automaton labeled with series to an automaton
* where all labels are series with one and only one element.
*
* @comment No cut-up work is done on input and output transitions.
* @note No cut-up work is done on input and output transitions.
*
* Works on all automata and transducers labeled with polynomial series,
* and on automata labeled with rational series.
......@@ -85,7 +85,7 @@ namespace vcsn
* @brief Transform an automaton labeled with series to an automaton
* where all labels are series with one and only one element.
*
* @comment No cut-up work is done on input and output transitions.
* @note No cut-up work is done on input and output transitions.
*
* Works on all automata and transducers labeled with polynomial series,
* and on automata labeled with rational series.
......
......@@ -2,7 +2,7 @@
//
// Vaucanson, a generic library for finite state machines.
//
// Copyright (C) 2001, 2002, 2003, 2004, 2005 The Vaucanson Group.
// Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006 The Vaucanson Group.
//
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License
......@@ -278,7 +278,7 @@ namespace vcsn {
Container& res, hstate_t from, delta_kind::transitions k);
/** store the output transitions of the state 'from' where
query(label(e)) = true in the container 'res' */
query(label(e)) = true in the container 'res' */
template <class S, class T,
typename Container, typename L>
void op_deltac(const AutomataBase<S>&, const IdentityView<T>&,
......@@ -288,7 +288,7 @@ namespace vcsn {
delta_kind::transitions k);
/** store the output transitions of the state 'from' where
query(label(e)) = true in the container 'res' */
query(label(e)) = true in the container 'res' */
template <class S, class T,
typename Container, typename L>
void op_letter_deltac(const AutomataBase<S>&, const IdentityView<T>&,
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
......@@ -17,7 +17,7 @@
//
/**
* @note CPP guard should not be inserted here as
* CPP guard should not be inserted here as
* VCSN_CONTEXT_NAMESPACE could be changed.
*/
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment