From 975a11566dc26d920326499db2fb4bebf0c00f2b Mon Sep 17 00:00:00 2001 From: Pavel Kirienko Date: Fri, 11 Jul 2014 19:02:57 +0400 Subject: [PATCH] libuavcan_dsdlc docstrings --- .../libuavcan_dsdl_compiler/__init__.py | 25 ++++++++++++++++++- libuavcan/dsdl_compiler/libuavcan_dsdlc | 10 +++++--- 2 files changed, 31 insertions(+), 4 deletions(-) diff --git a/libuavcan/dsdl_compiler/libuavcan_dsdl_compiler/__init__.py b/libuavcan/dsdl_compiler/libuavcan_dsdl_compiler/__init__.py index f0e51c8390..4142c45eff 100644 --- a/libuavcan/dsdl_compiler/libuavcan_dsdl_compiler/__init__.py +++ b/libuavcan/dsdl_compiler/libuavcan_dsdl_compiler/__init__.py @@ -4,9 +4,16 @@ # Copyright (C) 2014 Pavel Kirienko # +''' +This module implements the core functionality of the UAVCAN DSDL compiler for libuavcan. +Supported Python versions: 3.2+, 2.7. +It accepts a list of root namespaces and produces the set of C++ header files for libuavcan. +It is based on the DSDL parsing package from pyuavcan. +''' + from __future__ import division, absolute_import, print_function, unicode_literals import sys, os, logging, errno -from mako.template import Template +from mako.template import Template # TODO: get rid of the mako dependency from pyuavcan import dsdl # Python 2.7 compatibility @@ -27,6 +34,22 @@ class DsdlCompilerException(Exception): logger = logging.getLogger(__name__) def run(source_dirs, include_dirs, output_dir): + ''' + This function takes a list of root namespace directories (containing DSDL definition files to parse), a + possibly empty list of search directories (containing DSDL definition files that can be referenced from the types + that are going to be parsed), and the output directory path (possibly nonexistent) where the generated C++ + header files will be stored. + + Note that this module features lazy write, i.e. if an output file does already exist and its content is not going + to change, it will not be overwritten. This feature allows to avoid unnecessary recompilation of dependent object + files. + + Args: + source_dirs List of root namespace directories to parse. + include_dirs List of root namespace directories with referenced types (possibly empty). This list is + automaitcally extended with source_dirs. + output_dir Output directory path. Will be created if doesn't exist. + ''' assert isinstance(source_dirs, list) assert isinstance(include_dirs, list) output_dir = str(output_dir) diff --git a/libuavcan/dsdl_compiler/libuavcan_dsdlc b/libuavcan/dsdl_compiler/libuavcan_dsdlc index 852bd4cb3f..b7e05dc0c6 100755 --- a/libuavcan/dsdl_compiler/libuavcan_dsdlc +++ b/libuavcan/dsdl_compiler/libuavcan_dsdlc @@ -1,7 +1,7 @@ #!/usr/bin/env python # # UAVCAN DSDL compiler for libuavcan -# Written in Python 3, compatible with Python 2.7 +# Supported Python versions: 3.2+, 2.7. # # Copyright (C) 2014 Pavel Kirienko # @@ -27,8 +27,12 @@ def die(text): DEFAULT_OUTDIR = './dsdlc_generated' -DESCRIPTION = '''UAVCAN DSDL compiler. Takes an input directory that contains an hierarchy of DSDL -definitions and converts it into compatible hierarchy of C++ types for libuavcan.''' +DESCRIPTION = '''UAVCAN DSDL compiler for libuavcan. +Takes an input directory that contains an hierarchy of DSDL +definitions and converts it into compatible hierarchy of C++ types for libuavcan. +This script can be used directly from the source directory, no installation required! +Supported Python versions: 3.2+, 2.7. +''' argparser = argparse.ArgumentParser(description=DESCRIPTION) argparser.add_argument('source_dir', nargs='+', help='source directory with DSDL definitions')