[Bf-python] documentation markup proposal

[Michael Reimpell]

> The .py files are currently documented using epydoc which is
> python specific.
The Epytext markup language is closely related to javadoc. Even more, Epydoc 
can process plain javadoc and defines additional tags related to Python.

> The current plan for the C/C++ source is to use doxygen friendly markup,
> as mentioned in the 0-todo.txt file.
This is one reason why I proposed javadoc as markup language. Doxygen 
flawlessly processes javadoc (1.1) markup.

I dislike to have similar but different tag name, e.g. "\param <name>" for 
C/C++ and "@param <name>:" for Python, when I can use "@param <name>" for 
both. Also almost every developer will be familiar with some basic html tags. 
I can't think of a good reason why one should use dashes and hash characters 
to mark lists, especially when the syntax is different for C/C++ and Python 
documentation. Again you can just use html tags for both programming 
languages.

Regards,
Michael