Add docstrings to API

[GoogleCodeExporter]

Add docstrings to all the classes in the API.

Original issue reported on code.google.com by fullung@gmail.com on 8 Jun 2007 at 2:40

[GoogleCodeExporter]

Added parameter names as a start. Makes the C++ signatures more useful.

Original comment by fullung@gmail.com on 16 Jun 2007 at 12:19

[GoogleCodeExporter]

I'd vote for raising the priority of this ticket (it's on Low now) because the 
current docs are very minimal. I'd also 
suggest using Epydoc which creates docs like http://api.pyamf.org. I ran epydoc 
on pyactivemq and here's an 
example of the results: http://dev.collab.com/pyactivemq-docs. I'll create a 
new ticket with a setup.cfg 
containing some epydoc and setuptools options.

Original comment by thijs.triemstra@gmail.com on 27 May 2008 at 9:43

[GoogleCodeExporter]

I agree. How is your knowledge of Boost.Python? Would you like to tackle this 
issue?
I could add you as a developer of the pyactivemq project.

Original comment by fullung@gmail.com on 27 May 2008 at 9:54

• Added labels: Priority-Medium
• Removed labels: Priority-Low

[GoogleCodeExporter]

I seem to recall that there is some other Python documentation tool that is 
becoming
quite popular (I think mpi4py is using it). I'll try to find out the name.

Original comment by fullung@gmail.com on 27 May 2008 at 9:57

[GoogleCodeExporter]

The other tool is called Sphinx. Don't know if it's specifically geared towards 
API
documentation, but here is some nice output:

http://mentat.za.net/numpy/refguide/

Original comment by fullung@gmail.com on 27 May 2008 at 10:22

[GoogleCodeExporter]

I've heard of Sphinx, I think it's also going to be used for Python 2.6. I 
agree it's more a userguide type of 
documentation tool and not aimed towards docstrings. I've figured out how to 
add docstrings with Boost.Python 
using this guide 
(http://www.boost.org/doc/libs/1_35_0/libs/python/doc/v2/docstring_options.html)
 and 
wouldn't mind helping out with this ticket.

Original comment by thijs.triemstra@gmail.com on 27 May 2008 at 12:53

[GoogleCodeExporter]

I added docstrings for all classes and class properties, see update on 
http://dev.collab.com/pyactivemq-docs/ 
for generated api docs inc uml diagrams.

Now going to figure out how to document arguments and methods.

Original comment by thijs.triemstra@gmail.com on 27 May 2008 at 6:13

[GoogleCodeExporter]

Here's the first patch for the docstrings, which covers the classes and class 
properties, as described in comment 
#7. The docstrings come from the activemq-cpp api docs that we're wrapping 
here. Can you check it out fullung 
and let me know if you prefer a certain style/indentation etc, or if it's ok 
like this? I'm now going to figure out 
the docstrings for the args and methods, when I'm done I'll attach a second 
patch and then hopefully commit it 
all to the trunk.

Original comment by thijs.triemstra@gmail.com on 27 May 2008 at 7:00

Attachments:

• doc-classes.patch

[GoogleCodeExporter]

I like the general style. It looks like you stayed close to the way things are
currently documented in AMQCPP, which is good.

I'm wondering if there is a way to keep the documentation separate from the 
rest of
the code. My rationale here is that it makes the binding code harder to read, 
without
providing much value (someone hacking the binding code probably has a good idea 
of
how the API works).

Do you think it would be a) possible and b) make sense to move the docstrings 
into a
separate header or headers (or maybe keep them at the top of the source files) 
with
something of the form:

static const char* BytesMessage_reset_doc = "Some docs here";

and then have

.def("reset", &BytesMessage::reset, BytesMessage_reset_doc);

Thoughts?

Original comment by fullung@gmail.com on 27 May 2008 at 7:55

[GoogleCodeExporter]

It would definitely make sense to separate the docstrings and the actual code 
to make everything more readable. 
Your suggested header files sounds like a good plan, and it sounds like you 
know how to implement this. One 
monolithic file with all the docstrings called docstrings.cpp or something 
perhaps? I'll leave the implementation 
up to you, im no skilled c++ coder whatsoever (yet?) :) I'm going to continue 
to document the docstrings like I 
did in the patch, and once you implemented the suggestion in comment #9 I'll 
port everything to the new 
approach where necessary.

Original comment by thijs.triemstra@gmail.com on 27 May 2008 at 8:12

[GoogleCodeExporter]

Okay, I'll take one or two of the strings in your patch and commit it using one 
of
the schemes I described, and then you can continue with the rest of the docs in 
the
same way.

Original comment by fullung@gmail.com on 27 May 2008 at 8:15

[GoogleCodeExporter]

Added some ideas for organising the docstrings to Connection.cpp and 
MessageConsumer.cpp.

Check if this works for you and if so, go ahead and make that patch! Thanks for 
the
effort.

Original comment by fullung@gmail.com on 27 May 2008 at 8:27

[GoogleCodeExporter]

Ok looks good, I'll use that approach. 

Original comment by thijs.triemstra@gmail.com on 27 May 2008 at 8:35

[GoogleCodeExporter]

Added first docstrings batch in r161, more to come.

Original comment by thijs.triemstra@gmail.com on 27 May 2008 at 10:57

[GoogleCodeExporter]

I've cleaned up the indentation of this contribution a bit. Changes are in 
trunk.

Closing this issue until there's more docs to add.

Original comment by fullung@gmail.com on 19 Sep 2008 at 11:09

• Changed state: Fixed