Documentation is a very good thing.  Good documentation is even better. MRL provides a large array of Services  each of which contains a large number of methods.  When you are using Python, its nice to know what methods you have to work with.  Regrettably, we have a limited number of elves working on the project and they don't always have time to provide good documentation.

Here are some suggestions the elves have suggested.

  • Service pages are supposed to describe what a service does and give examples of how to do it.  There are several ways to get to a Service page. Right-Click-> Info which in turn just goes to http://myrobotlab.org:7777/service/<Service Type>   For example : http://myrobotlab.org/service/OpenCV 
    These pages are updated manually - so they get out of synch unless someone works on them.
  • Javadocs - On the service page there is a Javadoc link - javadoc this link provides more detailed information regarding the service. A list of methods - and sometimes comments on those methods.  Generating javadocs adds to the amount of time needed to build - so they are not created on every release and can fall out of sync
  • The GUI - The gui tab of MRL allows you to "see" what methods are available from each of the services.  It will give you all the methods you can use, there input parameters and return type.  Although it only offers the very basic amount of information, the nice thing is, IT IS ALWAYS UP TO DATE !!!

    Above you can see the list of methods the OpenCV service has, and their parameters after hitting the (in) button.  

    When you hit the (out) button you can see the methods return type.  I know now I can invoke the "capture()" method on the OpenCV service in Python with the following code.

    opencv = Runtime.start("opencv","OpenCV")
    opencv.capture()
     

  • The WebGUI - REST interface - The WebGUI's REST interface is similar in that it returns a dynamic list of methods you have access to.  The difference is that you can invoke these mesthods with a simple "click"

  • Python dir -

    Kwatters

     with is Python-Fu show'ed how to get all the  public methods and members from a service.  It's definately convienent if your working in Python.. only disadvanage is you don't know the parameters or their types, unless Kwatter knows ?
     

AdolphSmith

10 years 5 months ago

Nice Idea. 

kmcgerald

10 years 5 months ago

In over a year of using MRL I've never actually used the GUI tab for anything and didn't know you could get method lists from the inputs and outputs like that. 

kwatters

10 years 5 months ago

as another way to get at this..   lets say you have

foo = Runtime.createAndStarT("foo", "FooClass")

you can (in python)  do:

print(dir(foo))

this will display all methods available on object "foo" in the python std out window...  

enjoy!

I've seen dir examples before ..  and thought to myself .. "neat, reflection in Python !"

And here you demonstrated a very nice "quicky" :D

Apparently the PyObject wrapper displays exactly what you'd think it would.

Thanks for sharing you excellent Python-Fu

kwatters

10 years 5 months ago

Thx GroG..
Normally python interpreter you can use the built in help() function. This converts the first comment for each method on the python class into nicely formatted documetation. In many ways its python's version of javadoc.

This way you can create a python class and the comments surrouded by tripple qoute marks generates the documentatin for the help() function. Two issues,
1.the help function doesn't seem to work in MRL and
2. the classes that MRL is using from python are actually java classes...

maybe there is a way to expose the javadocs to python and enable the help() method ...

it seems like we need to make sure the object has an __doc__ attribute that contains the javadoc.. if possible, that'd be best.

for more info, check out the example python section in this Wikipedia page.

http://en.wikipedia.org/wiki/Docstring