Documentation string

Introduction

Py++ provides a convenient way to export documentation from C++ source files as Python documentation string

API description

mb = module_builder_t( ... )
my_class = mb.class_( 'my_class' )
my_class.documentation = '"very helpful documentation string"'
my_class.member_function( "do_nothing" ).documentation = \
    '"This function does nothing."'

In Py++ every class, which describes C++ declarations has documentation property. This property should contain valid C++ string or None.

Boost.Python not always provides functionality, which exports documentation string. In those cases, Py++ will not generate documentation string.

Also the previous method is pretty clear, it is not practical. There should be a better way, to complete the task. Lets take a look on module_builder_t.build_code_creator method. One of the arguments of this method is doc_extractor.

doc_extractor is a callable object, which takes one argument - reference to declaration.

def doc_extractor( decl ):
  ...

How it could help? Every declaration has location information:

• decl.location.file_name - absolute file name, where this declaration has been declared.
• decl.location.line - line number.

So, you can go to the source file and to extract declaration from it. Py++ will call doc_extractor on every exported declaration.

Now, when I think you understand what functionality Py++ provides. It is a time to say what functionality is missing. Py++ does not provide any documentation extractor. It is not completely true. You can find document extractor for doxygen format in contrib/doc_extractors directory. Georgiy Dernovoy has contributed it.