|
From: <rom...@us...> - 2006-07-20 19:12:27
|
Revision: 333 Author: roman_yakovenko Date: 2006-07-20 12:12:15 -0700 (Thu, 20 Jul 2006) ViewCVS: http://svn.sourceforge.net/pygccxml/?rev=333&view=rev Log Message: ----------- adding documentation for documentation strings Modified Paths: -------------- pyplusplus_dev/docs/documentation/www_configuration.py Added Paths: ----------- pyplusplus_dev/docs/documentation/doc_string.rest Added: pyplusplus_dev/docs/documentation/doc_string.rest =================================================================== --- pyplusplus_dev/docs/documentation/doc_string.rest (rev 0) +++ pyplusplus_dev/docs/documentation/doc_string.rest 2006-07-20 19:12:15 UTC (rev 333) @@ -0,0 +1,75 @@ +==================== +Documentation string +==================== + +.. contents:: Table of contents + +------------ +Introduction +------------ + +`pyplusplus`_ 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 `pyplusplus`_ every class, that describes C++ declarations has ``documentation`` +property. This property should contain valid C++ string or ``None``. + +`boost.python`_ not always provides functionality, that exports documentation string. +In those cases, `pyplusplus`_ 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, that 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. +`pyplusplus`_ will call ``doc_extractor`` on every exported declaration. + +Now, when I think you understand what functionality `pyplusplus`_ provides. +It is a time to say what functionality is missing. `pyplusplus`_ does not +provide any documentation extractor. It is not completely true. You can find +document extractor for `doxygen`_ format in ``contrib/doc_extractors`` directory. +It has been contributed by Georgiy Dernovoy. + + +.. _`doxygen` : http://www.stack.nl/~dimitri/doxygen/ +.. _`documentation string` : http://docs.python.org/tut/node6.html#SECTION006760000000000000000 +.. _`pyplusplus` : ./../pyplusplus.html +.. _`boost.python`: http://www.boost.org/libs/python/doc/index.html +.. _`Python`: http://www.python.org +.. _`GCC-XML`: http://www.gccxml.org + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: Modified: pyplusplus_dev/docs/documentation/www_configuration.py =================================================================== --- pyplusplus_dev/docs/documentation/www_configuration.py 2006-07-20 17:50:37 UTC (rev 332) +++ pyplusplus_dev/docs/documentation/www_configuration.py 2006-07-20 19:12:15 UTC (rev 333) @@ -1,5 +1,7 @@ name = 'documentation' main_html_file = 'index.html' -files_to_skip = ['indexing_suite_v2.html'] -names = { 'containers' : 'STL containers' - , 'how_to' : 'how to ... ?' } \ No newline at end of file +files_to_skip = ['indexing_suite_v2.html'] +names = { 'containers' : 'STL containers' + , 'how_to' : 'how to ... ?' + , 'doc_string' : 'documentation string' +} \ No newline at end of file This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
