Merge pull request #26 from jdlangs/docs

Add docstrings to exported types/functions

Author: jdlangs

src/gentypes.jl

@@ -3,7 +3,7 @@
 using Compat
 import Compat: String, Symbol
 
-export @rosimport, rostypegen, rostypereset, gentypes, cleartypes
+export @rosimport, rostypegen, rostypereset
 
 #Type definitions
 #Composite types for internal use. Keeps track of the imported types and helps
@@ -55,7 +55,7 @@ const _ros_builtin_types = Dict{String, Symbol}(
     "string"  => :String,
     "time"    => :Time,
     "duration"=> :Duration,
-    #Deprecated but supported
+    #Deprecated by ROS but supported here
     "char"    => :UInt8,
     "byte"    => :Int8,
     )
@@ -65,11 +65,23 @@ const _ros_builtin_types = Dict{String, Symbol}(
 @compat abstract type AbstractSrv end
 @compat abstract type AbstractService end
 
-#Rearranges the expression into a RobotOS._rosimport call. Input comes in as a
-#single package qualified expression, or as a tuple expression where the first
-#element is the same as the single expression case. Most of the code is just
-#error checking that the input takes that form.
+"""
+    @rosimport
+
+Import ROS message or service types into Julia. Call `rostypegen()` after all `@rosimport` calls.
+Package or type dependencies are also imported automatically as needed.
+
+Example usages:
+```julia
+  @rosimport geometry_msgs.msg.PoseStamped
+  @rosimport sensor_msgs.msg: Image, Imu
+  @rosimport nav_msgs.srv.GetPlan
+```
+"""
 macro rosimport(input)
+    #Rearranges the expression into a RobotOS._rosimport call. Input comes in as a single package
+    #qualified expression, or as a tuple expression where the first element is the same as the
+    #single expression case. Most of the code is just error checking that the input takes that form.
     @assert input.head in [:tuple, :(.), :(:)] "Improper @rosimport input"
     if input.head == :tuple
         @assert isa(input.args[1], Expr) "Improper @rosimport input"
@@ -124,8 +136,13 @@ function _rosimport(package::String, ismsg::Bool, names::String...)
     end
 end
 
-#Do the Julia type generation. This function is needed because we want to
-#create the modules in one go, rather than anytime @rosimport gets called
+"""
+    rostypegen()
+
+Initiate the Julia type generation process after importing some ROS types. Creates modules in `Main`
+with the same behavior as imported ROS modules in python. Should only be called once, after all
+`@rosimport` statements are done.
+"""
 function rostypegen()
     global _rospy_imports
     pkgdeps = _collectdeps(_rospy_imports)
@@ -135,9 +152,12 @@ function rostypegen()
     end
 end
 
-#Reset type generation process to start over with @rosimport. Does not remove
-#already generated modules! They will be replaced when rostypegen is called
-#again.
+"""
+    rostypereset()
+
+Clear out the previous `@rosimport`s, returning the type generation to its original state. Cannot do
+anything about already generated modules in `Main`.
+"""
 function rostypereset()
     global _rospy_imports
     global _rospy_objects

src/pubsub.jl

@@ -3,6 +3,13 @@ export Publisher, Subscriber, publish
 
 using Compat
 
+"""
+    Publisher{T}(topic; kwargs...)
+    Publisher(topic, T; kwargs...)
+
+Create an object to publish messages of type `T` on a topic. Keyword arguments are directly passed
+to rospy.
+"""
 type Publisher{MsgType<:AbstractMsg}
     o::PyObject
 
@@ -16,10 +23,23 @@ end
 Publisher{MT<:AbstractMsg}(topic::AbstractString, ::Type{MT}; kwargs...) =
     Publisher{MT}(ascii(topic); kwargs...)
 
+"""
+    publish(p::Publisher{T}, msg::T)
+
+Publish `msg` on `p`, a `Publisher` with matching message type.
+"""
 function publish{MT<:AbstractMsg}(p::Publisher{MT}, msg::MT)
     pycall(p.o["publish"], PyAny, convert(PyObject, msg))
 end
 
+"""
+    Subscriber{T}(topic, callback, cb_args=(); kwargs...)
+    Subscriber(topic, T, callback, cb_args=(); kwargs...)
+
+Create a subscription to a topic with message type `T` with a callback to use when a message is
+received, which can be any callable type. Extra arguments provided to the callback when invoked
+can be provided in the `cb_args` tuple. Keyword arguments are directly passed to rospy.
+"""
 type Subscriber{MsgType<:AbstractMsg}
     callback
     callback_args::Tuple

src/rospy.jl

@@ -3,13 +3,30 @@ export init_node, is_shutdown, spin,
        get_param, has_param, set_param, delete_param,
        logdebug, loginfo, logwarn, logerr, logfatal
 
-#General rospy functions
+"""
+    init_node(name; args...)
+
+Initialize this node, registering it with the ROS master. All arguments are passed on directly to
+the rospy init_node function.
+"""
 init_node(name::AbstractString; args...) =
     __rospy__[:init_node](ascii(name); args...)
+
+"""
+    is_shutdown()
+
+Return the shutdown status of the node.
+"""
 is_shutdown()          = __rospy__[:is_shutdown]()
+
 get_published_topics() = __rospy__[:get_published_topics]()
 get_ros_root()         = __rospy__[:get_ros_root]()
 
+"""
+    spin()
+
+Block execution and process callbacks/service calls until the node is shut down.
+"""
 function spin()
     #Have to make sure both Julia tasks and python threads can wake up so
     #can't just call rospy's spin
@@ -19,6 +36,12 @@ function spin()
 end
 
 #Parameter server API
+"""
+    get_param(param_name, default=nothing)
+
+Request the value of a parameter from the parameter server, with optional default value. If no
+default is given, throws a `KeyError` if the parameter cannot be found.
+"""
 function get_param(param_name::AbstractString, def=nothing)
     try
         if def == nothing
@@ -30,17 +53,36 @@ function get_param(param_name::AbstractString, def=nothing)
         throw(KeyError(pycall(pybuiltin("str"), PyAny, ex.val)[2:end-1]))
     end
 end
+
+"""
+    set_param(param_name, val)
+
+Set the value of a parameter on the parameter server.
+"""
 set_param(param_name::AbstractString, val) =
     __rospy__[:set_param](ascii(param_name), val)
+
+"""
+    has_param(param_name)
+
+Return a boolean specifying if a parameter exists on the parameter server.
+"""
 has_param(param_name::AbstractString) =
     __rospy__[:has_param](ascii(param_name))
+
+"""
+    delete_param(param_name)
+
+Delete a parameter from the parameter server. Throws a `KeyError` if no such parameter exists.
+"""
 function delete_param(param_name::AbstractString)
     try
         __rospy__[:delete_param](ascii(param_name))
     catch ex
         throw(KeyError(pycall(pybuiltin("str"), PyAny, ex.val)[2:end-1]))
     end
 end
+
 #Doesn't work for some reason
 #rospy_search_param(param_name::AbstractString) =
 #    __rospy__[:rospy_search_param](ascii(param_name))
@@ -53,6 +95,14 @@ logwarn(msg, args...)  = __rospy__[:logwarn](msg, args...)
 logerr(msg, args...)   = __rospy__[:logerr](msg, args...)
 logfatal(msg, args...) = __rospy__[:logfatal](msg, args...)
 
+"""
+    logdebug, loginfo, logwarn, logerr, logfatal
+
+Call the rospy logging system at the corresponding message level, passing a message and other
+arguments directly.
+"""
+logdebug, loginfo, logwarn, logerr, logfatal
+
 #Node information
 get_name()             = __rospy__[:get_name]()
 get_namespace()        = __rospy__[:get_namespace]()

src/services.jl

@@ -3,6 +3,13 @@ export Service, ServiceProxy, wait_for_service
 
 using Compat
 
+"""
+    ServiceProxy{T}(name; kwargs...)
+    ServiceProxy(name, T; kwargs...)
+
+Create a proxy object used to invoke a remote service. Use `srv_proxy(msg_request)` with the object
+to invoke the service call. Keyword arguments are directly passed to rospy.
+"""
 type ServiceProxy{SrvType <: AbstractService}
     o::PyObject
 
@@ -32,6 +39,13 @@ end
     resp
 end
 
+"""
+    Service{T}(name, callback; kwargs...)
+    Service(name, T, callback; kwargs...)
+
+Create a service object that can receive requests and provide responses. The callback can be of
+any callable type. Keyword arguments are directly passed to rospy.
+"""
 type Service{SrvType <: AbstractService}
     handler
     srv_obj::PyObject
@@ -71,6 +85,12 @@ function Service{ST<:AbstractService}(name::AbstractString, srv::Type{ST}, handl
     Service{ST}(ascii(name), handler; kwargs...)
 end
 
+"""
+    wait_for_service(srv_name; kwargs...)
+
+Block until the specified service is available. Keyword arguments are directly passed to rospy.
+Throws an exception if the waiting timeout period is exceeded.
+"""
 function wait_for_service(service::AbstractString; kwargs...)
     try
         __rospy__[:wait_for_service](ascii(service); kwargs...)

src/time.jl

@@ -8,6 +8,15 @@ export Time, Duration, Rate, to_sec, to_nsec, get_rostime, rossleep
 #Time type definitions
 @compat abstract type TVal end
 
+"""
+    Time(secs, nsecs), Time(), Time(t::Real)
+
+Object representing an absolute time from a fixed past reference point at nanosecond precision.
+
+Basic arithmetic can be performed on combinations of `Time` and `Duration` objects that make sense.
+For example, if `t::Time` and `d::Duration`, `t+d` will be a `Time`, `d+d` a Duration`, `t-d` a
+`Time`, `d-d` a `Duration`, and `t-t` a `Duration`.
+"""
 immutable Time <: TVal
     secs::Int32
     nsecs::Int32
@@ -19,6 +28,15 @@ end
 Time() = Time(0,0)
 Time(t::Real) = Time(t,0)
 
+"""
+    Duration(secs, nsecs), Duration(), Duration(t::Real)
+
+Object representing a relative period of time at nanosecond precision.
+
+Basic arithmetic can be performed on combinations of `Time` and `Duration` objects that make sense.
+For example, if `t::Time` and `d::Duration`, `t+d` will be a `Time`, `d+d` a `Duration`, `t-d` a
+`Time`, `d-d` a `Duration`, and `t-t` a `Duration`.
+"""
 immutable Duration <: TVal
     secs::Int32
     nsecs::Int32
@@ -45,7 +63,6 @@ function _canonical_time(secs, nsecs)
     (secs32 + addsecs, crnsecs)
 end
 
-#Temporal arithmetic
 +(t1::Time,     t2::Duration) = Time(    t1.secs+t2.secs, t1.nsecs+t2.nsecs)
 +(t1::Duration, t2::Time)     = Time(    t1.secs+t2.secs, t1.nsecs+t2.nsecs)
 +(t1::Duration, t2::Duration) = Duration(t1.secs+t2.secs, t1.nsecs+t2.nsecs)
@@ -62,14 +79,44 @@ convert(::Type{PyObject}, t::Time)     = __rospy__[:Time](    t.secs,t.nsecs)
 convert(::Type{PyObject}, t::Duration) = __rospy__[:Duration](t.secs,t.nsecs)
 
 #Real number conversions
+"""
+    to_sec(t)
+
+Return the value of a ROS time object in absolute seconds (with nanosecond precision)
+"""
 to_sec{T<:TVal}(t::T) = t.secs + 1e-9*t.nsecs
+
+"""
+    to_nsec(t)
+
+Return the value of a ROS time object in nanoseconds as an integer.
+"""
 to_nsec{T<:TVal}(t::T) = 1_000_000_000*t.secs + t.nsecs
 convert{T<:TVal}(::Type{Float64}, t::T) = to_sec(t)
 
 #Comparisons
-=={T<:TVal}(t1::T, t2::T)     = (t1.secs == t2.secs) && (t1.nsecs == t2.nsecs)
+=={T<:TVal}(t1::T, t2::T) = (t1.secs == t2.secs) && (t1.nsecs == t2.nsecs)
 isless{T<:TVal}(t1::T, t2::T) = to_nsec(t1) < to_nsec(t2)
 
+"""
+    Rate(hz::Real), Rate(d::Duration)
+
+Used to allow a loop to run at a fixed rate. Construct with a frequency or `Duration` and use with
+`rossleep` or `sleep`. The rate object will record execution time of other work in the loop and
+modify the sleep time to compensate, keeping the loop rate as consistent as possible.
+"""
+type Rate
+    duration::Duration
+    last_time::Time
+end
+Rate(d::Duration) = Rate(d, get_rostime())
+Rate(hz::Real) = Rate(Duration(1.0/hz), get_rostime())
+
+"""
+    get_rostime()
+
+Return the current ROS time as a `Time` object.
+"""
 function get_rostime()
     t = try
         __rospy__[:get_rostime]()
@@ -78,8 +125,20 @@ function get_rostime()
     end
     convert(Time, t)
 end
+
+"""
+    RobotOS.now()
+
+Return the current ROS time as a `Time` object.
+"""
 now() = get_rostime()
 
+"""
+    rossleep(t)
+
+Sleep and process callbacks for a number of seconds implied by the type and value of `t`, which may
+be a real-value, a `Duration` object, or a `Rate` object.
+"""
 function rossleep(td::Duration)
     #Busy sleep loop needed to allow both julia and python async activity
     tnsecs = to_nsec(td)
@@ -91,15 +150,6 @@ function rossleep(td::Duration)
 end
 rossleep(t::Real) = rossleep(Duration(t))
 
-sleep(t::Duration) = rossleep(t)
-
-type Rate
-    duration::Duration
-    last_time::Time
-end
-Rate(d::Duration) = Rate(d, get_rostime())
-Rate(hz::Real) = Rate(Duration(1.0/hz), get_rostime())
-
 function rossleep(r::Rate)
     ctime = get_rostime()
     if r.last_time > ctime
@@ -113,4 +163,11 @@ function rossleep(r::Rate)
         r.last_time = ctime
     end
 end
+
+"""
+    sleep(t::Duration), sleep(t::Rate)
+
+Call `rossleep` with a `Duration` or `Rate` object. Use `rossleep` to specify sleep time directly.
+"""
+sleep(t::Duration) = rossleep(t)
 sleep(t::Rate) = rossleep(t)