Skip to content
Browse files

Added some edoc-compatible documentation

  • Loading branch information...
1 parent ffaaade commit 9c81d131a397a9257acb17a3194ae705ffc79098 @3lectrologos 3lectrologos committed May 15, 2010
View
24 Makefile
@@ -15,6 +15,8 @@ EBIN = $(TOP)/ebin
INCLUDE = $(TOP)/include
+DOC = $(TOP)/doc
+
# ----------------------------------------------------
# Flags
# ----------------------------------------------------
@@ -29,7 +31,7 @@ TARGETS = \
gui \
pulse \
wx \
- pra1 \
+ src \
utest
GUI_MODULES = \
@@ -43,20 +45,21 @@ PULSE_MODULES = \
instrument \
scheduler
-PRA1_MODULES = \
- sched \
+SRC_MODULES = \
instr \
- log
+ log \
+ sched \
+ util
MODULES = \
$(GUI_MODULES) \
$(PULSE_MODULES) \
- $(PRA1_MODULES)
+ $(SRC_MODULES)
ERL_DIRS = \
gui \
pulse \
- pra1
+ src
vpath %.hrl include
vpath %.erl $(ERL_DIRS)
@@ -67,12 +70,17 @@ all: $(TARGETS)
clean:
rm -f *.sh
rm -f $(EBIN)/*.beam
+ rm -f $(DOC)/*.html $(DOC)/*.css $(DOC)/edoc-info $(DOC)/*.png
+
+.PHONY: doc
+doc: util.beam
+ erl -noshell -pa $(EBIN) -s util doc $(TOP) -s init stop
gui: $(GUI_MODULES:%=%.beam)
pulse: $(PULSE_MODULES:%=%.beam)
-pra1: $(PRA1_MODULES:%=%.beam)
+src: $(SRC_MODULES:%=%.beam)
wx: pulse_gui.sh
@@ -105,4 +113,4 @@ scheduler.beam: gui.hrl
instr.beam: gen.hrl
log.beam: gen.hrl
-sched.beam: gen.hrl
+sched.beam: gen.hrl
View
3 README.md
@@ -1,7 +1,8 @@
Howto
======
-* Build: make
+* Build: make
+* Build doc: make doc
* Cleanup: make clean
* Run pulse GUI: pulse_gui.sh
* Run unit tests: test.sh
View
3 doc/.gitignore
@@ -0,0 +1,3 @@
+*
+!overview.edoc
+!.gitignore
View
2 doc/overview.edoc
@@ -0,0 +1,2 @@
+@author Maria Christakis
+@author Alkis Gotovos
View
BIN pra1/doc/pra1.pdf
Binary file not shown.
View
105 pra1/doc/pra1.tex
@@ -1,105 +0,0 @@
-\documentclass[a4paper,10pt]{article}
-
-\usepackage[T1]{fontenc}
-\renewcommand{\ttdefault}{pcr}
-
-\usepackage[pdftex]{graphicx}
-\usepackage{listings}
-
-\title{Prototype A1}
-\author{Alkis Gotovos}
-
-\begin{document}
-\lstset{language=Erlang, basicstyle=\small \ttfamily}
-
-\begin{titlepage}
-\maketitle
-\thispagestyle{empty}
-\end{titlepage}
-
-\section{Introduction}
-The aim of this document is to describe the \emph{structure} and \emph{features}
-of a fully functional prototype for the Erlang concurrency testing tool that we
-intend to develop. Our rationale is to use this prototype (PRA1) to gain insight
-into the inner workings of our main project and detect potential pitfalls
-as early as possible.
-
-In the following sections we present the subset of functionality that we
-shall implement in PRA1, as well as an overview of its architecture
-(which possibly forms a structural preview for our main project).
-
-\section{Functionality}
-Being the very first prototype, PRA1 shall only implement a core subset of the
-overall functionality. Specifically, we shall consider the following Erlang
-"constructs" for now:
-\begin{itemize}
- \item The \lstinline+spawn/1+ BIF
- \item The \lstinline+send/2+ BIF (equivalently the \lstinline+!+ operator)
- \item The simple \lstinline+receive+ expression (not containing an \lstinline+after+ clause)
-\end{itemize}
-
-The current implementation shall accept a single erlang module for analysis
-and output a log, containing all possible process interleavings
-with respect to the aforementioned "constructs".
-
-\section{Instrumentation}
-To be able to analyze a module we have to use wrapper functions and statements in place of
-the standard Erlang ones. The easiest way to do this (without having to mess with the Erlang runtime system)
-is to preprocess the module source before handing it over to the scheduler for analysis. This preprocessing
-step is called \emph{instrumentation}.
-
-Next, we present the code transformations done by the instrumenter for the three constructs mentioned above
-(functions with a \lstinline+'rep_'+ prefix are custom wrapper functions).
-
-\lstset{emph = {Function, Process, Message, Pattern1, PatternN,
- GuardSeq1, GuardSeqN, Body1, BodyN}, emphstyle = \emph}
-\begin{itemize}
- \item The statement
- \begin{lstlisting}
- spawn(Function)
- \end{lstlisting}
- will become
- \begin{lstlisting}
- sched:rep_spawn(Function)
- \end{lstlisting}
-
- \item The statement
- \begin{lstlisting}
- Process ! Message
- \end{lstlisting}
- will become
- \begin{lstlisting}
- sched:rep_send(Process, Message)
- \end{lstlisting}
-
- \item Finally, the statement
- \begin{lstlisting}
- receive
- Pattern1 [when GuardSeq1] -> Body1;
- ...;
- PatternN [when GuardSeqN] -> BodyN
- end
- \end{lstlisting}
- will become
- \begin{lstlisting}
- sched:rep_receive(
- fun(Aux) -> receive
- Pattern1 [when GuardSeq1] -> Body1;
- ...;
- PatternN [when GuardSeqN] -> BodyN
- after 0 -> Aux()
- end
- end)
- \end{lstlisting}
-\end{itemize}
-
-\section{Structure}
-
-\begin{figure}[htb]
- \centering
- \includegraphics[width=350px]{pra1_arch}
- \caption{Architecture overview}
-\end{figure}
-
-
-\end{document}
View
BIN pra1/doc/pra1_arch.pdf
Binary file not shown.
View
10 pra1/instr.erl → src/instr.erl
@@ -1,9 +1,17 @@
+%% @doc: The instrumenter.
+
-module(instr).
-export([instrument_and_load/1]).
-include("gen.hrl").
-%% Instrument and load a list of files.
+%% @spec instrument_and_load([file()]) -> 'ok' | 'error'
+%% @doc: Instrument, compile and load a list of files.
+%%
+%% Each file is first validated (i.e. checked whether it will compile
+%% successfully). If no errors are encountered, the file gets instrumented,
+%% compiled and loaded. If all of these actions are successfull, the function
+%% returns `ok', otherwise `error' is returned. No `.beam' files are produced.
-spec instrument_and_load([file()]) -> 'ok' | 'error'.
instrument_and_load([]) ->
View
12 pra1/log.erl → src/log.erl
@@ -1,27 +1,35 @@
+%% @doc: Logging and error reporting interface.
+
-module(log).
-export([internal/1, internal/2, log/1, log/2]).
-include("gen.hrl").
+%% @spec internal(string()) -> none()
+%% @doc: Print an internal error message and halt.
-spec internal(string()) -> no_return().
-%% Print an internal error message.
internal(String) ->
io:format("(Internal) " ++ String),
halt(?RET_INTERNAL_ERROR).
+%% @spec internal(string(), [term()]) -> none()
+%% @doc: Like `internal/1', but prints a formatted message using arguments.
-spec internal(string(), [term()]) -> no_return().
internal(String, Args) ->
io:format("(Internal) " ++ String, Args),
halt(?RET_INTERNAL_ERROR).
+%% @spec log(string()) -> 'ok'
+%% @doc: Add a message to log (for now just print to stdout).
-spec log(string()) -> 'ok'.
-%% Add a message to log (for now just print to stdout).
log(String) ->
io:format(String).
+%% @spec log(string(), [term()]) -> 'ok'
+%% @doc: Like `log/1', but prints a formatted message using arguments.
-spec log(string(), [term()]) -> 'ok'.
log(String, Args) ->
View
43 pra1/sched.erl → src/sched.erl
@@ -1,3 +1,5 @@
+%% @doc: The scheduler.
+
-module(sched).
%% UI related exports.
@@ -35,6 +37,11 @@
%%% Types
%%%----------------------------------------------------------------------
+%% @type: lid() = string().
+%% @type: dest() = pid() | port() | atom() | {atom(), atom()}.
+
+%% @type: analysis_ret() = 0 | 1 | 2.
+
-type lid() :: string().
-type dest() :: pid() | port() | atom() | {atom(), node()}.
@@ -75,8 +82,9 @@
%%% User interface
%%%----------------------------------------------------------------------
-%% Instrument one or more files and produce all interleavings of running
-%% Mod:Fun(Args).
+%% @spec analyze([file()], atom(), atom(), [term()]) -> analysis_ret()
+%% @doc: Instrument one or more files and produce all interleavings of running
+%% `Mod:Fun(Args)'.
-spec analyze([file()], module(), atom(), [term()]) -> analysis_ret().
analyze(Files, Mod, Fun, Args) ->
@@ -378,7 +386,9 @@ block() ->
#sched{msg = continue} -> true
end.
-%% Replacement for link/1.
+%% @spec: rep_link(pid() | port()) -> 'true'
+%% @doc: Replacement for `link/1'.
+%%
%% Just yield after linking.
-spec rep_link(pid() | port()) -> 'true'.
@@ -388,11 +398,15 @@ rep_link(Pid) ->
rep_yield(),
Result.
-%% Replacement for yield/0.
+%% @spec rep_yield() -> 'true'
+%% @doc: Replacement for `yield/0'.
+%%
%% The calling process is preempted, but remains in the active set and awaits
%% a message to continue.
-%% NOTE: Besides replacing yield/0, this function is heavily used by the
-%% instrumenter before other calls (e.g. spawn, send, etc.).
+%%
+%% Note: Besides replacing `yield/0', this function is heavily used by other
+%% functions of the instrumentation interface.
+
-spec rep_yield() -> 'true'.
rep_yield() ->
@@ -401,10 +415,12 @@ rep_yield() ->
#sched{msg = continue} -> true
end.
-%% Replacement for an erlang `receive` statement (without an `after` clause).
+%% @spec rep_receive(function((function()) -> term())) -> term()
+%% @doc: Replacement for a `receive' statement.
+%%
%% The first time the process is scheduled it searches its mailbox. If no
%% matching message is found, it blocks (i.e. is moved to the blocked set).
-%% When a new message arrives the process is woken up (see `send` handler).
+%% When a new message arrives the process is woken up.
%% The check mailbox - block - wakeup loop is repeated until a matching message
%% arrives.
-spec rep_receive(fun((fun()) -> term())) -> term().
@@ -415,6 +431,9 @@ rep_receive(Fun) ->
rep_receive_aux(Fun) ->
Fun(fun() -> block(), rep_receive_aux(Fun) end).
+%% @spec rep_receive_notify(pid(), term()) -> 'ok'
+%% @doc: Auxiliary function used in the `receive' statetement instrumentation.
+%%
%% Called first thing after a message has been received, to inform the scheduler
%% about the message received and the sender.
-spec rep_receive_notify(pid(), term()) -> 'ok'.
@@ -424,7 +443,9 @@ rep_receive_notify(From, Msg) ->
rep_yield(),
ok.
-%% Replacement for send/2 (and the equivalent ! operator).
+%% @spec rep_send(dest(), term()) -> term()
+%% @doc: Replacement for `send/2' (and the equivalent `!' operator).
+%%
%% Just yield after sending.
-spec rep_send(dest(), term()) -> term().
@@ -434,7 +455,9 @@ rep_send(Dest, Msg) ->
rep_yield(),
RealMsg.
-%% Replacement for spawn/1.
+%% @spec rep_spawn(fun()) -> pid()
+%% @doc: Replacement for `spawn/1'.
+%%
%% The argument provided is the argument of the original spawn call.
%% When spawned, the new process has to yield.
-spec rep_spawn(fun()) -> pid().
View
13 src/util.erl
@@ -0,0 +1,13 @@
+%% @doc: Utility functions.
+
+-module(util).
+-export([doc/1]).
+
+%% @spec doc(string()) -> 'ok'
+%% @doc: Build documentation using edoc.
+-spec doc(string()) -> 'ok'.
+
+doc(AppDir) ->
+ AppName = yet_to_be_named,
+ Options = [],
+ edoc:application(AppName, AppDir, Options).

0 comments on commit 9c81d13

Please sign in to comment.
Something went wrong with that request. Please try again.