Introspect documentation for methods, signals, properties

[Matthew Johnson]

On Fri, 17 Feb 2006, Thiago Macieira wrote:

>
> I think I misunderstand here the purpose of this documentation.
>
> Is it supposed to be used by running programs at all? Or just shown to the
> user when browsing the list of available methods and signals?
>
> I'm suggesting Doxygen because it allows us to:
> 2) put the documentation back into C/C++ header files when creating stubs
> for remote objects/interfaces

Remember, C/C++ isn't the only language, I'd like to be able to put this
documentation into Javadoc for the Java bindings, and perl/python I
believe have yet another format. If the annotation (or whatever) just
specifies a single string for each method and argument, this is trivial
to convert into any of these languages for the bindings.

> 3) auto-generate this XML documentation by extracting existing Doxygen
> documentation in source code

And other bindings maintainers will have to translate into Doxygen from
their language doc format, so it is not saving that much effort.

> But I'd then suggest that, instead of an annotation, we use a
> <documentation>....</documentation> tag. That would allow for a better
> handling of Doxygen/whatever texts. If modifying the DTD in this manner

It depends what we want, As I said in my other email, it would be good
to have a brief single-sentence description for each method in the
introspection data itself. I'm not convinced that the entire API manual
should go in there, however. Whoever wrote the API in the first place
should have complete API docs generated in the original language that
was used, I don't think we need to duplicate this when you translate the
API into your language-of-choice.

Matt
-- 
Matthew Johnson
http://www.matthew.ath.cx/