Commit 378c8a7c authored by Guillaume Lazzara's avatar Guillaume Lazzara
Browse files

Introduce a technical documentation.

	* doc/Makefile.am: Add technical as subdir.

	* doc/doxyfuns.sty: Do not force the use of png images.

	* doc/examples/devel/dispatch.cc.raw,
	* doc/examples/devel/facade.cc.raw,
	* doc/examples/devel/impl.cc.raw: New. Examples used in the
	developer documentation.

	* doc/technical/Makefile.am,
	* doc/technical/figures/file_layout.pdf,
	* doc/technical/figures/file_layout.png,
	* doc/technical/technical.tex: New.

git-svn-id: https://svn.lrde.epita.fr/svn/oln/trunk@4599 4aad255d-cdde-0310-9447-f3009e2ae8c0
parent 135e3061
2009-10-01 Guillaume Lazzara <z@lrde.epita.fr>
Introduce a technical documentation.
* doc/Makefile.am: Add technical as subdir.
* doc/doxyfuns.sty: Do not force the use of png images.
* doc/examples/devel/dispatch.cc.raw,
* doc/examples/devel/facade.cc.raw,
* doc/examples/devel/impl.cc.raw: New. Examples used in the
developer documentation.
* doc/technical/Makefile.am,
* doc/technical/figures/file_layout.pdf,
* doc/technical/figures/file_layout.png,
* doc/technical/technical.tex: New.
2009-10-01 Guillaume Lazzara <z@lrde.epita.fr>
 
* doc/ref_guide/ref_guide.tex: Add a new section about common compilation errors.
......@@ -23,6 +23,7 @@ include $(top_srcdir)/milena/doc/doc.mk
SUBDIRS = \
examples \
ref_guide \
technical \
tutorial \
white_paper
......
......@@ -176,7 +176,7 @@ $$
\label{#1}%
}
\renewcommand{\doxyimg}[2]{%
\pgfimage[width=#2]{#1.png}%
\pgfimage[width=#2]{#1}%
\label{#1}%
}
\renewcommand{\doxyref}[1]{\ref{#1}}
......
namespace internal
{
// Generic case, whatever the image value and domain
// types.
template <typename I, typename N>
mln_concrete(I)
erosion_tolerant_dispatch(trait::image::kind::any,
trait::image::speed::any,
const I& input, const N& nbh,
unsigned rank)
{
return impl::generic::erosion_tolerant(input,
nbh,
rank);
}
// The image has bool values and is defined on a box.
template <typename I, typename N>
mln_concrete(I)
erosion_tolerant_dispatch(trait::image::kind::logic,
trait::image::speed::fastest,
const I& input, const N& nbh,
unsigned rank)
{
return
impl::erosion_tolerant_on_set_fastest(input,
nbh,
rank);
}
// Dispatch entry point.
template <typename I, typename N>
inline
mln_concrete(I)
erosion_tolerant_dispatch(const Image<I>& input,
const Neighborhood<N>& nbh,
unsigned rank)
{
return
erosion_tolerant_dispatch(mln_trait_image_kind(I)(),
mln_trait_image_speed(I)(),
exact(input),
exact(nbh),
rank);
}
} // end of namespace mln::internal
template <typename I, typename N>
inline
mln_concrete(I)
erosion_tolerant(const Image<I>& input, const Neighborhood<N>& nbh,
unsigned rank)
{
trace::entering("morpho::erosion_tolerant");
mln_precondition(exact(input).is_valid());
mln_precondition(exact(nbh).is_valid());
mln_concrete(I) output
= internal::erosion_tolerant_dispatch(input,
nbh,
rank);
trace::exiting("morpho::erosion_tolerant");
return output;
}
namespace impl
{
namespace generic
{
template <typename I, typename N>
mln_concrete(I)
erosion_tolerant_on_set(const Image<I>& input_,
const Neighborhood<N>& nbh_,
unsigned rank)
{
trace::entering("impl::generic::erosion_tolerant");
// Do it...
trace::exiting("impl::generic::erosion_tolerant");
return output;
}
}
template <typename I, typename N>
mln_concrete(I)
erosion_tolerant_on_set_fastest(const Image<I>& input_,
const Neighborhood<N>& nbh_,
unsigned rank)
{
trace::entering("impl::erosion_tolerant_on_set_fastest");
// Do it...
trace::exiting("impl::erosion_tolerant_on_set_fastest");
return output;
}
} // end of namespace impl
# Copyright (C) 2009 EPITA Research and Development Laboratory (LRDE).
#
# This file is part of Olena.
#
# Olena is free software: you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation, version 2 of the License.
#
# Olena is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Olena. If not, see <http://www.gnu.org/licenses/>.
#
.PHONY: technical technical-html
include $(top_srcdir)/milena/doc/doc.mk
TEXINPUTS ="$(DOC_SRCDIR):$(OUTPUTS_SRCDIR):$(srcdir):\
$(SPLIT_OUTPUTS_SRCDIR):$(IMG_SRCDIR):$(SPLIT_EXAMPLES_SRCDIR):"
technical: technical-html technical-pdf
# FIXME: As in milena/doc/Makefile.am, we should probably strip
# $(srcdir) prefixes from target variables, e.g. instead of:
#
# FOO = $(srcdir)/foo.pdf
# $(FOO): foo.tex bar.tex
# dist_doc_DATA = $(FOO)
#
# we should use:
#
# FOO = foo.pdf
# $(srcdir)/$(FOO): foo.tex bar.tex
# dist_doc_DATA = $(FOO)
#
# since it minimizes installation issues (see milena/doc/Makefile.am
# and Vaucanson's doc/Makefile.am).
# FIXME: Distributed products should be generated in the source dir.
# That's actually the case, *but* the current solution is not clean
# and might break sometimes. The clean approach is to create a
# temporary directory, try to generate the documentation there, and
# move its contents to the source dir in case of success. If the
# product is a directory, also refresh a timestamp (in the source
# dir).
# Intermediate product for the various doc targets of the parent
# directory.
#
# This is not a bug: TECHNICAL_HH is meant to have a `.hh'
# extension, since it is later parsed by Doxygen, which complains
# about `.html' files.
TECHNICAL_HH = $(srcdir)/technical.hh
technical-html: $(TECHNICAL_HH)
$(TECHNICAL_HH): technical.tex $(srcdir)/../figures.stamp
$(DOC_SRCDIR)/tools/todoxygen.sh \
$< $(DOC_SRCDIR)/technical $(DOC_SRCDIR)
# Final product.
TECHNICAL_PDF = $(srcdir)/technical.pdf
technical-pdf: $(TECHNICAL_PDF)
$(TECHNICAL_PDF): technical.tex $(srcdir)/../figures.stamp
TEXINPUTS=$(TEXINPUTS) pdflatex $<
TEXINPUTS=$(TEXINPUTS) pdflatex $<
TEXINPUTS=$(TEXINPUTS) pdflatex $< \
test "$(top_srcdir)" == "$(top_builddir)" \
|| mv -f $(builddir)/technical.pdf $(srcdir)
# FIXME: Regenerating figures.stamp requires make to go back to the
# parent directory. We already do the opposite (descending from
# milena/doc/ to milena/doc/tutorial/Makefile in milena/doc/ to update
# tutorial.hh). This is not sound. We probably want to put together
# somes of these files, and maybe get rid of some directories, or at
# least move most of the Makefile machinery into
# milena/doc/Makefile.am.
$(srcdir)/../figures.stamp:
cd .. && $(MAKE) $(AM_MAKEFLAGS) fig-convert
dist_doc_DATA = $(TECHNICAL_PDF)
EXTRA_DIST = \
technical.tex \
$(TECHNICAL_HH)
CLEANFILES = \
technical.aux technical.toc technical.log technical.bbl technical.out \
*blg *.lot \
$(TECHNICAL_PDF) \
*.haux *.hh *.html *.htoc \
technical.html \
technical.idx \
$(TECHNICAL_HH)
#<<lrde
# Pretend the documentation is up-to-date.
.PHONY: fake-doc
fake-doc:
touch $(TECHNICAL_HH)
touch $(TECHNICAL_PDF)
# The converse of the previous rule, voiding the timestamps.
.PHONY: void-doc
void-doc:
touch $(srcdir)/technical.tex
#>>
%% Copyright (C) 2009 EPITA Research and Development Laboratory (LRDE)
%%
%% This file is part of Olena.
%%
%% Olena is free software: you can redistribute it and/or modify it under
%% the terms of the GNU General Public License as published by the Free
%% Software Foundation, version 2 of the License.
%%
%% Olena is distributed in the hope that it will be useful,
%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
%% General Public License for more details.
%%
%% You should have received a copy of the GNU General Public License
%% along with Olena. If not, see <http://www.gnu.org/licenses/>.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Milena's technical documentation. %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass{report}
%\usepackage{hevea}
\usepackage{html}
\usepackage{graphicx}
\usepackage{makeidx}
\usepackage{xcolor}
\usepackage{color}
\usepackage{hyperref}
\usepackage{pgf}
\usepackage{hyperref}
\usepackage{doxyfuns}
\usepackage{milena}
\title{Milena -- Technical documentation}
\author{LRDE}
\date{}
\makeindex
\begin{document}
% Doxygen use only - Generate the left menu.
%Write foreword below.
\begin{htmlonly}
\backslash endhtmlonly
\backslash page techdoc Technical Documentation
- \backslash subpage codingstyle
- \backslash subpage extendlib
- \backslash subpage ressources
\backslash htmlonly
\end{htmlonly}
\begin{latexonly}
\maketitle
%===============================================================
\chapter*{Copyright}
Copyright (C) 2009 EPITA Research and Development Laboratory (LRDE).
This document is part of Olena.
Olena is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, version 2 of the License.
Olena is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License
along with Olena. If not, see $<$http://www.gnu.org/licenses/$>$.
\tableofcontents
\end{latexonly}
%===============================================================
\doxychapter{codingstyle}{Coding Style}
The coding style is going to be updated. However, there are few
reference documents available here:
\begin{itemize}
\item https://trac.lrde.org/olena/wiki/CodingStyle
\item https://olena.lrde.epita.fr/cgi-bin/twiki/view/Olena/CodingStyle010
\end{itemize}
%===============================================================
\doxychapter{extendlib}{Extend the Library}
%***************************************************************
\doxysection{newvaluetype}{Add a new image value type}
% - classes parentes/de base
% - Ajouts d'operateurs associes
%***************************************************************
\doxysection{newimagetype}{Add a new image type}
%***************************************************************
\clearpage
\doxysection{newroutine}{Add a new routine}
Writing a new routine in Milena requires a specific layout in the
code. This layout is described in figure \ref{figures/file_layout}.
\begin{center}
\doxyimg{figures/file_layout}{8cm}
\end{center}
For a better understanding, we are going to comment this figure
(fig. \ref{figures/file_layout}) from the bottom to the top.
\begin{itemize}
\item \textbf{Facade}. The facade is the public routine that will be
called by the user. It \should not contains any processing code
but call dispatch routines. It \must be fully generic.
An example:
\doxyrawcode{devel/facade}
\item \textbf{Implementation dispatch}. According to specific
information, the dispatch will call the proper implementation of
the algorithm. The dispatch is almost always static. It might
contains dynamic dispatch in very specific cases. Dispatch
function names are composed of the routine name with
``\_dispatch'' appended to it.
Dispatch entry point routine must have the same prototype as the
facade.
Dispatch routines are not intended to be called by the user.
An example:
\doxyrawcode{devel/dispatch}
\item \textbf{Specific implementation}. Implementation routine are
intended to be called by the user. Thus, they must have an
explicit name of what they do and what they take as
parameter. They implement de processing code which may be specific
for certain types.
\var{namespace impl} may also have a sub namespace called
\var{generic} for the generic algorithm.
An example:
\doxyrawcode{devel/impl}
\item \textbf{Shared tests and internal routines}. This is the right
place to move all the internal routines related to this new
routine. They will be hidden to the user.
\item \textbf{Facade prototype}. This is what the user should see
first if the file is edited. The documentation should be written
here.
\end{itemize}
Note that all parts of the file except the ``facade prototype'' are included between \var{MLN\_INCLUDE\_ONLY} guards.
%===============================================================
\doxychapter{ressources}{Developer Ressources}
%***************************************************************
\doxysection{quality}{Project Quality}
\begin{itemize}
\item QA Center : https://trac.lrde.org/olena/wiki/QACenter
\item Buildbot : https://buildfarm.lrde.org/buildfarm/oln/
\item Trac : http://trac.lrde.org/olena
\end{itemize}
%***************************************************************
\doxysection{qna}{Questions and Answers}
The best way to keep in touch with the latest patches or ask your
questions is to subscribe to our mailing lists.
Currently four mailing-lists are available:
\begin{tabular}{l l}
\textbf{Olena} & Discussion about the project Olena \\
\textbf{Olena-bugs} & Bugs from Olena projects \\
\textbf{Olena-core} & Internal list for the Olena project \\
\textbf{Olena-patches} & patches for the Olena project \\
\end{tabular}
You can subscribe to these mailing lists at the following address:
\begin{center}
\begin{verbatim}
https://www.lrde.epita.fr/mailman/listinfo/
\end{verbatim}
\end{center}
Just click on the name of the mailing list you want to subscribe to
and fill out the form.
\end{document}
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