[help-texinfo] Overloading function defs inside and across languages

[Jean-Louis Leroy]

Hello,

I need to document a library that exists in C++, Java and
Perl. 

I have decided to write a language-independant documentation that
begins with "semantic" specs followed by language-specific that
document the function calling conventions etc.

For example, in the semantic doc for Storage I explain that it has an
insert() methods for inserting one object or a list of objects, that
inserting an object that is already persistent is an error, etc.

In the Perl appendix, I give the two legal ways of calling insert():

   insert(@list)
   insert($obj)

...or perhaps:

   @id = insert(@list)
   $id = insert($obj)

And in the C++ appendix:

    template<typename T> ID insert(const T* obj)
    template<typename I, typename O> O insert(I first, I last)

Furthermore, 'ID' in this example is not a real type, it's a meta-type
that can be 'string' if the Storage is actually a XML::Storage and
'struct { int obj, type } ID' for a Relational::Storage.

I have looked at the @defmethod and @deftypemethod commands, but how
do I deal with overloading? And what will the index look like? Ideally
it would be something like:

         insert, C++ 49,50    (the two entries are on different pages)
         insert, Perl 89      (they fit on the same page)

Looking for inspiration, I searched for a texinfo doc of the standard
C++ library (specifically templates like vector<>), but didn't find
any. And by the same token I'd like to find texinfo samples for OO
code written in Perl and Java, and docs that encompass several
languages.

Any advice or wisdom will also be most welcome.
-- 
Jean-Louis Leroy
Sound Object Logic
http://www.soundobjectlogic.com