Document C++ API

LibCarla/source/carla/client/Actor.cpp

@@ -40,7 +40,7 @@ namespace client {
     GetEpisode().Lock()->SetActorSimulatePhysics(*this, enabled);
   }
 
-  void Actor::Destroy() {
+  bool Actor::Destroy() {
     if (_is_alive) {
       // Let the exceptions leave the function, IsAlive() will still be true.
       _is_alive = !GetEpisode().Lock()->DestroyActor(*this);
@@ -49,6 +49,7 @@ namespace client {
           "attempting to destroy an actor that is already dead:",
           GetDisplayId());
     }
+    return _is_alive;
   }
 
 } // namespace client

LibCarla/source/carla/client/Actor.h

@@ -14,6 +14,7 @@
 namespace carla {
 namespace client {
 
+  /// Represents an actor in the simulation.
   class Actor
     : public EnableSharedFromThis<Actor>,
       private profiler::LifetimeProfiled,
@@ -27,29 +28,58 @@ namespace client {
 
     virtual ~Actor() = default;
 
+    /// Return the current location of the actor.
+    ///
+    /// @note This function does not call the simulator, it returns the location
+    /// received in the last tick.
     geom::Location GetLocation() const;
 
+    /// Return the current transform of the actor.
+    ///
+    /// @note This function does not call the simulator, it returns the
+    /// transform received in the last tick.
     geom::Transform GetTransform() const;
 
+    /// Return the current 3D velocity of the actor.
+    ///
+    /// @note This function does not call the simulator, it returns the
+    /// velocity received in the last tick.
     geom::Vector3D GetVelocity() const;
 
+    /// Return the current 3D acceleration of the actor.
+    ///
+    /// @note This function does not call the simulator, it returns the
+    /// acceleration calculated after the actor's velocity.
     geom::Vector3D GetAcceleration() const;
 
+    /// Teleport the actor to @a location.
     void SetLocation(const geom::Location &location);
 
+    /// Teleport and rotate the actor to @a transform.
     void SetTransform(const geom::Transform &transform);
 
+    /// Enable or disable physics simulation on this actor.
     void SetSimulatePhysics(bool enabled = true);
 
-    const auto &Serialize() const {
-      return Super::GetActorDescription();
-    }
-
+    /// @warning This method only checks whether this instance of Actor has
+    /// called the Destroy() method, it does not check whether the actor is
+    /// actually alive in the simulator.
     bool IsAlive() const {
       return _is_alive;
     }
 
-    virtual void Destroy();
+    /// Tell the simulator to destroy this Actor, and return whether the actor
+    /// was successfully destroyed.
+    ///
+    /// @note It has no effect if the Actor was already successfully destroyed.
+    ///
+    /// @warning This function blocks until the destruction operation is
+    /// completed by the simulator.
+    virtual bool Destroy();
+
+    const auto &Serialize() const {
+      return Super::GetActorDescription();
+    }
 
   private:
 

LibCarla/source/carla/client/Client.h

@@ -27,18 +27,23 @@ namespace client {
         uint16_t port,
         size_t worker_threads = 0u);
 
+    /// Set a timeout for networking operations. If set, any networking
+    /// operation taking longer than @a timeout throws rpc::timeout.
     void SetTimeout(time_duration timeout) {
       _simulator->SetNetworkingTimeout(timeout);
     }
 
+    /// Return the version string of this client API.
     std::string GetClientVersion() const {
       return _simulator->GetClientVersion();
     }
 
+    /// Return the version string of the simulator we are connected to.
     std::string GetServerVersion() const {
       return _simulator->GetServerVersion();
     }
 
+    /// Return an instance of the world currently active in the simulator.
     World GetWorld() const {
       return World{_simulator->GetCurrentEpisode()};
     }

LibCarla/source/carla/client/Sensor.cpp

@@ -32,12 +32,6 @@ namespace client {
 
   void Sensor::Listen(CallbackFunctionType callback) {
     log_debug(GetDisplayId(), ": subscribing to stream");
-    if (_is_listening) {
-      log_warning(
-          "attempting to listen to stream but sensor is already listening:",
-          GetDisplayId());
-      return;
-    }
     GetEpisode().Lock()->SubscribeToSensor(*this, std::move(callback));
     _is_listening = true;
   }
@@ -53,11 +47,11 @@ namespace client {
     _is_listening = false;
   }
 
-  void Sensor::Destroy() {
+  bool Sensor::Destroy() {
     if (_is_listening) {
       Stop();
     }
-    Actor::Destroy();
+    return Actor::Destroy();
   }
 
 } // namespace client

LibCarla/source/carla/client/Sensor.h

@@ -23,15 +23,28 @@ namespace client {
 
     using CallbackFunctionType = std::function<void(SharedPtr<sensor::SensorData>)>;
 
+    /// Register a @a callback to be executed each time a new measurement is
+    /// received.
+    ///
+    /// @warning Calling this function on a sensor that is already listening
+    /// steals the data stream from the previously set callback. Note that
+    /// several instances of Sensor (even in different processes) may point to
+    /// the same sensor in the simulator.
     void Listen(CallbackFunctionType callback);
 
+    /// Stop listening for new measurements.
     void Stop();
 
+    /// Return whether this Sensor instance is currently listening to the
+    /// associated sensor in the simulator.
     bool IsListening() const {
       return _is_listening;
     }
 
-    void Destroy() override;
+    /// @copydoc Actor::Destroy()
+    ///
+    /// Additionally stop listening.
+    bool Destroy() override;
 
   private:
 

LibCarla/source/carla/client/TrafficLight.h

@@ -23,6 +23,10 @@ namespace client {
 
     explicit TrafficLight(ActorInitializer init) : Actor(std::move(init)) {}
 
+    /// Return the current state of the traffic light.
+    ///
+    /// @note This function does not call the simulator, it returns the
+    /// traffic light state received in the last tick.
     TrafficLightState GetState();
   };
 

LibCarla/source/carla/client/Vehicle.h

@@ -19,10 +19,17 @@ namespace client {
 
     explicit Vehicle(ActorInitializer init) : Actor(std::move(init)) {}
 
+    /// Switch on/off this vehicle's autopilot.
     void SetAutopilot(bool enabled = true);
 
+    /// Apply @a control to this vehicle.
     void ApplyControl(const Control &control);
 
+    /// Return the control last applied to this vehicle.
+    ///
+    /// @warning This function only takes into account the control applied to
+    /// this instance of Vehicle. Note that several instances of Vehicle (even
+    /// in different processes) may point to the same vehicle in the simulator.
     const Control &GetControl() const {
       return _control;
     }

LibCarla/source/carla/client/World.cpp

@@ -62,7 +62,7 @@ namespace client {
   SharedPtr<Actor> World::TrySpawnActor(
       const ActorBlueprint &blueprint,
       const geom::Transform &transform,
-      Actor *parent_actor) {
+      Actor *parent_actor) noexcept {
     try {
       return SpawnActor(blueprint, transform, parent_actor);
     } catch (const std::exception &) {

LibCarla/source/carla/client/World.h

@@ -32,32 +32,51 @@ namespace client {
     World &operator=(const World &) = default;
     World &operator=(World &&) = default;
 
+    /// Get the id of the episode associated with this world.
     uint32_t GetId() const;
 
+    /// Return the map name of this world. E.g., Town01.
+    ///
+    /// @note When playing in editor, the map name can be different than the
+    /// usual map name of the town.
     const std::string &GetMapName() const;
 
+    /// Return the list of blueprints available in this world. This blueprints
+    /// can be used to spawning actor into the world.
     SharedPtr<BlueprintLibrary> GetBlueprintLibrary() const;
 
+    /// Return the spectator actor. The spectator controls the view in the
+    /// simulator window.
     SharedPtr<Actor> GetSpectator() const;
 
+    /// Retrieve the weather parameters currently active in the world.
     rpc::WeatherParameters GetWeather() const;
 
+    /// Change the weather in the simulation.
     void SetWeather(const rpc::WeatherParameters &weather);
 
+    /// Return a list with all the actors currently present in the world.
     SharedPtr<ActorList> GetActors() const;
 
+    /// Spawn an actor into the world based on the @a blueprint provided at @a
+    /// transform. If a @a parent is provided, the actor is attached to
+    /// @a parent.
     SharedPtr<Actor> SpawnActor(
         const ActorBlueprint &blueprint,
         const geom::Transform &transform,
         Actor *parent = nullptr);
 
+    /// Same as SpawnActor but return nullptr on failure instead of throwing an
+    /// exception.
     SharedPtr<Actor> TrySpawnActor(
         const ActorBlueprint &blueprint,
         const geom::Transform &transform,
-        Actor *parent = nullptr);
+        Actor *parent = nullptr) noexcept;
 
+    /// Block calling thread until a world tick is received.
     Timestamp WaitForTick(time_duration timeout) const;
 
+    /// Register a @a callback to be called every time a world tick is received.
     void OnTick(std::function<void(Timestamp)> callback);
 
   private:

LibCarla/source/carla/client/detail/ActorFactory.h

@@ -21,10 +21,16 @@ namespace detail {
   class ActorFactory {
   public:
 
+    /// Create an Actor based on the provided @a actor_description. @a episode
+    /// must point to the episode in which the actor is living.
+    ///
+    /// If @a garbage_collection_policy is GarbageCollectionPolicy::Enabled, the
+    /// shared pointer returned is provided with a custom deleter that calls
+    /// Destroy() on the actor.
     static SharedPtr<Actor> MakeActor(
         EpisodeProxy episode,
         rpc::Actor actor_description,
-        GarbageCollectionPolicy gc);
+        GarbageCollectionPolicy garbage_collection_policy);
   };
 
 } // namespace detail

LibCarla/source/carla/client/detail/Simulator.h

@@ -140,6 +140,10 @@ namespace detail {
       return _episode->GetActors();
     }
 
+    /// If @a gc is GarbageCollectionPolicy::Enabled, the shared pointer
+    /// returned is provided with a custom deleter that calls Destroy() on the
+    /// actor. If @gc is GarbageCollectionPolicy::Enabled, the default garbage
+    /// collection policy is used.
     SharedPtr<Actor> SpawnActor(
         const ActorBlueprint &blueprint,
         const geom::Transform &transform,