Mentions légales du service

Skip to content
Snippets Groups Projects
Commit 000aa27e authored by hhakim's avatar hhakim
Browse files

Add a script for editing Faust.m to generate a Matlab inline doc from doxygen code doc. 

- Goal: avoiding doc duplication in Faust.m.
- Update matlab wrapper cmake script to call the parser script.
- By the way update slightly API doc for both wrappers.
parent ada0c0d6
Branches
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
gen_doc/gen_matlab_inline_doc_from_doxy_blocks.sh 0 → 100755
+ 106
− 0
View file @ 000aa27e
#!/bin/bash
# this script takes a matlab script documented as defined by doxygen matlab plugin
# parse the doxy doc block and generate a new file .m with inline doc corresponding to the doxygen doc (filtering doxygen tags)
# if a inner code comment block is already present in a function (in the start, just after its name) it will be replaced
function usage {
echo "USAGE: $0 <input_path.m> <output_path.m>"
}
function usage_exit {
usage
exit $1
}
function parse_doxy_block {
local FUNC=$(echo $1 | tr '[a-z]' '[A-Z]')
local FUNC_LINE=$(echo "$3" | sed -e 's/^[[:blank:]]\+//')
echo -e "$2" | sed -e "{
s/^\s*%=\+//;
s/%>\s*@brief/%% $FUNC/;
s/^\([[:blank:]]\+\)%> @param F/\1% SPECS: $FUNC_LINE:\n\1\t% - Parameter F: /;
s/%>/%/;
s/^/\t/;
s/Usage/Usage:/
s/@param\s\([^[:blank:]]\+\)/- Parameter \1: /;
s/@code/=========== code ===========/;
s/@endcode/========= end code =========/;
s/\(Examples\?\)/\1:/
s/<[^>]*>//g;
s/&nbsp;/ /g;
s/@retval/Returns/g;
s/@[^[:blank:]]* \?//g;
s/\\\./\./g
}"
}
# parse input args
[[ $# -ge 2 && -r "$1" ]] && INPUT_FILE="$1" || usage_exit 1
[[ -z $(dirname "$2") || -d "$(dirname $2)" ]] && OUTPUT_FILE="$2" || usage_exit 2
# get function names
FUNCTIONS=$(sed -ne 's/^\s*function[[:blank:]]\+\([^=]\+=\)\?\s*\([^([:blank:]]\+\).*$/\2/p' "$INPUT_FILE")
[[ -z "${FUNCTIONS}" ]] && echo "ERROR in getting the list of functions in $INPUT_FILE" && exit 3
cp "$INPUT_FILE" "$OUTPUT_FILE"
[ ! "$?" = 0 ] && echo "ERROR in copying file." >&2 && exit 4
DOXY_BLOCKS_LIMITS=($(sed -ne '/\s*\%=\+\s*/=' "$INPUT_FILE"))
typeset -i DOXY_BLOCK_ID=0
for FUNC in $FUNCTIONS
do
# get the line numbers of the current inline code block
INLINE_DOC_LINE_NUMS=($(sed -ne '/^\s*function[[:blank:]]\+\([^=]\+=\)\?\s*\('$FUNC'\)[[:blank:]]*(.*$/,/^[[:blank:]]*[^%]\+$/=' $OUTPUT_FILE))
# delete not empty inline code doc block
if [ ${#INLINE_DOC_LINE_NUMS[*]} -gt 2 ]
then
INLINE_DOC_START_NUM=${INLINE_DOC_LINE_NUMS[1]}
INLINE_DOC_END_NUM=${INLINE_DOC_LINE_NUMS[-2]}
[[ $INLINE_DOC_START_NUM =~ [[:digit:]]+ && $INLINE_DOC_END_NUM =~ [[:digit:]]+ ]] && sed -i "${INLINE_DOC_START_NUM},${INLINE_DOC_END_NUM}d" ${OUTPUT_FILE}
[ ! "$?" = 0 ] && echo "ERROR sed deleting old inline doc block." >&2 && exit 5
fi
# get the doxy block for the function
DOXY_BLOCK=$(sed -ne "$((${DOXY_BLOCKS_LIMITS[$DOXY_BLOCK_ID]}+1)),$((${DOXY_BLOCKS_LIMITS[$(($DOXY_BLOCK_ID+1))]}-1))p" "$INPUT_FILE")
[[ "$DEBUG" = "DOXY_BLOCK" ]] && echo "DOXY_BLOCK=$DOXY_BLOCK"
# get the new line position of the function
FUNC_LINE=$(sed -ne '/^\s*function[[:blank:]]\+\([^=]\+=\)\?\s*\('$FUNC'\)[[:blank:]]*(.*$/=' "$OUTPUT_FILE")
[[ "$DEBUG" = "FUNC_LINE" ]] && echo FUNC_LINE=$FUNC_LINE FUNC=$FUNC >&2
[[ ! $FUNC_LINE =~ [[:digit:]]+ ]] && echo "ERROR in getting function $FUNC line number in $OUTPUT_FILE." >&2 && DOXY_BLOCK_ID+=2 && continue
# insert parsed block
FUNC_DEF_LINE=$(sed -ne $FUNC_LINE'p' $OUTPUT_FILE)
sed -ne '1,'$FUNC_LINE'p' $OUTPUT_FILE > ${OUTPUT_FILE}_tmp
# parse doxy block for inline block
INLINE_BLOCK=$(parse_doxy_block $FUNC "$DOXY_BLOCK" "$FUNC_DEF_LINE")
echo -e "$INLINE_BLOCK" >> ${OUTPUT_FILE}_tmp
sed -ne $(($FUNC_LINE+1))','$(wc -l ${OUTPUT_FILE} | awk '{print $1}')'p' $OUTPUT_FILE >> ${OUTPUT_FILE}_tmp
[ "$?" = 0 ] && mv ${OUTPUT_FILE}_tmp ${OUTPUT_FILE}
DOXY_BLOCK_ID+=2
done
# filter header for class doc
HEADER_START_END=($(sed -ne '/^[[:blank:]]*% ==*/=' $OUTPUT_FILE))
OUT_NUM_LINES=$(wc -l ${OUTPUT_FILE}| awk '{print $1}')
DOXY_HEADER=$(sed -ne "$((${HEADER_START_END[0]}+1)),$((${HEADER_START_END[1]}-1))p" ${OUTPUT_FILE})
[[ "$DEBUG" = "DOXY_HEADER" ]] && echo "DOXY_HEADER=$DOXY_HEADER"
INLINE_HEADER=$(parse_doxy_block "FAUST" "$DOXY_HEADER")
[[ "$DEBUG" = "INLINE_HEADER" ]] && echo "INLINE_HEADER=$INLINE_HEADER"
echo -e "$INLINE_HEADER" | sed 's/^[[:blank:]]\+//' > ${OUTPUT_FILE}_tmp
echo -e '\n\n' >> ${OUTPUT_FILE}_tmp
sed -ne "${HEADER_START_END[0]},${OUT_NUM_LINES}p" $OUTPUT_FILE >> ${OUTPUT_FILE}_tmp
[ "$?" = 0 ] && mv ${OUTPUT_FILE}_tmp ${OUTPUT_FILE}
wrapper/matlab/CMakeLists.txt
+ 5
− 2
View file @ 000aa27e
...@@ -14,10 +14,13 @@ foreach(MATLAB_TOOLS FaustCore faust_decompose generate_params) ...@@ -14,10 +14,13 @@ foreach(MATLAB_TOOLS FaustCore faust_decompose generate_params)
endforeach() endforeach()
# install Faust.m in the CMAKE_INSTALL_MATLAB_PREFIX directory # install Faust.m in the CMAKE_INSTALL_MATLAB_PREFIX directory
if(WIN32)
configure_file(${FAUST_MATLAB_SRC_DIR}/Faust.m ${FAUST_MATLAB_BIN_DIR}/Faust.m COPYONLY) configure_file(${FAUST_MATLAB_SRC_DIR}/Faust.m ${FAUST_MATLAB_BIN_DIR}/Faust.m COPYONLY)
#install(FILES ${FAUST_MATLAB_BIN_DIR}/Faust.m DESTINATION ${CMAKE_INSTALL_MATLAB_PREFIX} PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_WRITE GROUP_EXECUTE WORLD_READ WORLD_WRITE WORLD_EXECUTE) #install(FILES ${FAUST_MATLAB_BIN_DIR}/Faust.m DESTINATION ${CMAKE_INSTALL_MATLAB_PREFIX} PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_WRITE GROUP_EXECUTE WORLD_READ WORLD_WRITE WORLD_EXECUTE)
else()
execute_process(COMMAND ${FAUST_DOC_SRC_DIR}/gen_matlab_inline_doc_from_doxy_blocks.sh ${FAUST_MATLAB_SRC_DIR}/Faust.m ${FAUST_MATLAB_BIN_DIR}/Faust.m ERROR_QUIET)
#TODO: get back error result with ERROR_VARIABLE SCRIPT_ERROR_VARIABLE and copy simply the script as a fallback solution
endif()
file(GLOB CPP_MEXTOOLS_FILES "${FAUST_MATLAB_TOOLS_SRC_DIR}/*.cpp") file(GLOB CPP_MEXTOOLS_FILES "${FAUST_MATLAB_TOOLS_SRC_DIR}/*.cpp")
# include directory # include directory
......
wrapper/matlab/Faust.m
+ 25
− 16
View file @ 000aa27e
...@@ -40,7 +40,7 @@ ...@@ -40,7 +40,7 @@
%% %%
% ====================================================================== % ======================================================================
%> @brief FAµST Matlab class %> @brief FAµST Matlab wrapper main class.
%> %>
%> This class represents a given dense matrix by a product of sparse matrices (i.e. Faust). %> This class represents a given dense matrix by a product of sparse matrices (i.e. Faust).
%> The main goal of Faust representation is to speed up operations on that matrix, especially the multiplication. Besides the time optimization, a Faust can reduce the memory space size needed both for storage and loading. %> The main goal of Faust representation is to speed up operations on that matrix, especially the multiplication. Besides the time optimization, a Faust can reduce the memory space size needed both for storage and loading.
...@@ -60,6 +60,8 @@ ...@@ -60,6 +60,8 @@
%> Other important limitation is that contrary to a Matlab native dense matrix a Faust is immutable. It means that you cannot affect elements of a Faust using the affectation operator `=' like you do with a Matlab matrix (e.g. `M(i,j) = 2'). %> Other important limitation is that contrary to a Matlab native dense matrix a Faust is immutable. It means that you cannot affect elements of a Faust using the affectation operator `=' like you do with a Matlab matrix (e.g. `M(i,j) = 2').
%> That limitation is the reason why the Matlab built-in `SUBSASGN()' is not implemented in this class. %> That limitation is the reason why the Matlab built-in `SUBSASGN()' is not implemented in this class.
%> %>
%> For more information about FAµST take a look at http://faust.inria.fr.
%>
% ====================================================================== % ======================================================================
classdef Faust classdef Faust
properties (SetAccess = private, Hidden = true) properties (SetAccess = private, Hidden = true)
...@@ -240,15 +242,21 @@ classdef Faust ...@@ -240,15 +242,21 @@ classdef Faust
%====================================================================== %======================================================================
%> @brief Multiplies the Faust or its transpose by the A dense matrix. %> @brief Multiplies the Faust F by A.' or A which is a dense matrix or a Faust object.
%>
%> This function overloads a Matlab built-in function.
%> %>
%> @b WARNING: this function costs as much as Faust.mtimes. %> @b WARNING: if A is a matrix the function costs get_num_factors(F) matrix multiplications.
%> In that case its use is discouraged except for test purpose. However if A is a Faust object,
%> it costs the same that a Faust initialization with a number of factors equal to
%> F.get_num_factors()+A.get_num_factors() (like you can do directly with Faust.Faust).
%> %>
%> @param A the matrix to multiply (dense matrix). %> @param F the Faust object.
%> @param A The dense matrix to multiply or a Faust object.
%> @param trans equals 1 to calculate C=F'*A %> @param trans equals 1 to calculate C=F'*A
%> or 0 to calculate C=F*A. %> or 0 to calculate C=F*A.
%> %>
%> @retval C The multiplication result (dense matrix). %> @retval C The multiplication result (a dense matrix or a Faust object depending on what A is).
%> %>
%> <p> @b See @b also mtimes. %> <p> @b See @b also mtimes.
%====================================================================== %======================================================================
...@@ -391,7 +399,7 @@ classdef Faust ...@@ -391,7 +399,7 @@ classdef Faust
%> <p/>@b See @b also Faust.transpose, Faust.conj %> <p/>@b See @b also Faust.transpose, Faust.conj
%> %>
%====================================================================== %======================================================================
function F_ctrans=ctranspose(F) function F_ctrans = ctranspose(F)
%% CTRANSPOSE ' Complex conjugate transposed Faust (overloaded Matlab built-in function). %% CTRANSPOSE ' Complex conjugate transposed Faust (overloaded Matlab built-in function).
% %
% F_trans = ctranspose(F) is called for syntax F' (complex conjugate transpose) when F is a Faust. % F_trans = ctranspose(F) is called for syntax F' (complex conjugate transpose) when F is a Faust.
...@@ -429,7 +437,7 @@ classdef Faust ...@@ -429,7 +437,7 @@ classdef Faust
%> <p/>@b See @b also Faust.get_factor, Faust.get_num_factors, Faust.ctranspose %> <p/>@b See @b also Faust.get_factor, Faust.get_num_factors, Faust.ctranspose
%> %>
%====================================================================== %======================================================================
function F_conj=conj(F) function F_conj = conj(F)
%% CONJ ' Complex conjugate Faust (overloaded Matlab built-in function). %% CONJ ' Complex conjugate Faust (overloaded Matlab built-in function).
% %
% F_conj = conj(F) For a complex F, F_conj == REAL(F) - i*IMAG(F) % F_conj = conj(F) For a complex F, F_conj == REAL(F) - i*IMAG(F)
...@@ -697,9 +705,9 @@ classdef Faust ...@@ -697,9 +705,9 @@ classdef Faust
%> @retval The Faust object requested. %> @retval The Faust object requested.
%> %>
%> @b Example %> @b Example
%> @code %> @code
%> F = Faust.rand([2, 5], [50, 100], .5) %> F = Faust.rand([2, 5], [50, 100], .5)
%> i = randi(min(size(F)), 1, 2) %> i = randi(min(size(F)), 1, 2)
%> i1 = i(1);i2 = i(2) %> i1 = i(1);i2 = i(2)
%> %>
%> F(i1,i2) % a Faust representing a matrix with only one element %> F(i1,i2) % a Faust representing a matrix with only one element
...@@ -710,11 +718,11 @@ classdef Faust ...@@ -710,11 +718,11 @@ classdef Faust
%> F(3:4,2:5) % from row 3 to line 4, each row containing only elements from column 2 to 5. %> F(3:4,2:5) % from row 3 to line 4, each row containing only elements from column 2 to 5.
%> %>
%> F(1:end,5:end-1) % from row 1 to end row, each one containing only elements from column 5 to column before the last one. %> F(1:end,5:end-1) % from row 1 to end row, each one containing only elements from column 5 to column before the last one.
%> @endcode %> @endcode
%> %>
%> <p>@b See @b also Faust.end. %> <p>@b See @b also Faust.end.
%========================================================================================== %==========================================================================================
function submatrix=subsref(F,S) function submatrix = subsref(F,S)
%% SUBSREF Subscripted reference (overloaded Matlab built-in function). %% SUBSREF Subscripted reference (overloaded Matlab built-in function).
% %
% F(I,J) is an array formed from the elements of the rectangular % F(I,J) is an array formed from the elements of the rectangular
...@@ -784,6 +792,7 @@ classdef Faust ...@@ -784,6 +792,7 @@ classdef Faust
%> @param F the Faust to display information about. %> @param F the Faust to display information about.
%> %>
%> %>
%======================================================================
function F = subsasgn(F,S,B) function F = subsasgn(F,S,B)
%% SUBSASGN (WARNING not implemented) (overloaded Matlab built-in function) %% SUBSASGN (WARNING not implemented) (overloaded Matlab built-in function)
% %
...@@ -876,7 +885,7 @@ classdef Faust ...@@ -876,7 +885,7 @@ classdef Faust
%> %>
%> %>
%====================================================================== %======================================================================
function norm=norm(F,varargin) function norm = norm(F,varargin)
%% NORM Faust norm (overloaded Matlab built-in function). %% NORM Faust norm (overloaded Matlab built-in function).
% %
% norm(F,1) when F is a Faust returns L1 norm of F (the largest % norm(F,1) when F is a Faust returns L1 norm of F (the largest
...@@ -931,7 +940,7 @@ classdef Faust ...@@ -931,7 +940,7 @@ classdef Faust
%> %>
%> <p>@b See @b also Faust.rcg, Faust.density. %> <p>@b See @b also Faust.rcg, Faust.density.
%========================================================================================== %==========================================================================================
function nz=nnz_sum(F) function nz = nnz_sum(F)
%% NNZ Number of nonzero elements in a Faust (overloaded Matlab built-in function). %% NNZ Number of nonzero elements in a Faust (overloaded Matlab built-in function).
% %
% nz = nnz_sum(F) is the number of nonzero elements in the Faust F. % nz = nnz_sum(F) is the number of nonzero elements in the Faust F.
...@@ -963,7 +972,7 @@ classdef Faust ...@@ -963,7 +972,7 @@ classdef Faust
%> %>
%> <p/>@b See @b also Faust.nnz_sum, Faust.rcg %> <p/>@b See @b also Faust.nnz_sum, Faust.rcg
%====================================================================== %======================================================================
function dens=density(F) function dens = density(F)
%% DENSITY Density of the Faust. %% DENSITY Density of the Faust.
% %
% dens = density(F) when F is a Faust returns the % dens = density(F) when F is a Faust returns the
...@@ -998,7 +1007,7 @@ classdef Faust ...@@ -998,7 +1007,7 @@ classdef Faust
%> %>
%> <p>@b See @b also Faust.density, Faust.nnz_sum. %> <p>@b See @b also Faust.density, Faust.nnz_sum.
%========================================================================================== %==========================================================================================
function speed_up=rcg(F) function speed_up = rcg(F)
%% RCG Relative Complexity Gain (inverse of the density) %% RCG Relative Complexity Gain (inverse of the density)
% %
% speed_up = rcg(F) when F is Faust, returns the % speed_up = rcg(F) when F is Faust, returns the
......
wrapper/python/pyfaust.py
+ 2
− 1
View file @ 000aa27e
...@@ -48,7 +48,7 @@ import FaustCorePy ...@@ -48,7 +48,7 @@ import FaustCorePy
class Faust: class Faust:
"""FAµST Python class. """FAµST Python wrapper main class.
This class represents a given dense matrix by a product of sparse matrices This class represents a given dense matrix by a product of sparse matrices
(i.e. Faust). (i.e. Faust).
The main goal of Faust representation is to speed up operations on that The main goal of Faust representation is to speed up operations on that
...@@ -88,6 +88,7 @@ class Faust: ...@@ -88,6 +88,7 @@ class Faust:
That limitation is the reason why the Python built-in `__setitem__()' is not That limitation is the reason why the Python built-in `__setitem__()' is not
implemented in this class. implemented in this class.
For more information about FAµST take a look at http://faust.inria.fr.
""" """
def __init__(F, factors=None, scale=1.0, filepath=None, core_obj=None): def __init__(F, factors=None, scale=1.0, filepath=None, core_obj=None):
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment