more behaviors docs

docs/src/agent_definitions.md

@@ -9,6 +9,7 @@ You can implement your own agent definition by creating a new type inheriting fr
 The following three functions must be implemented for your custom type:
 
 ```@docs
+    AbstractAgentDefinition
     length
     width
     class

docs/src/behaviors.md

@@ -7,8 +7,19 @@ the vehicles present in the environment, a behavior model returns an action to e
 
 ## Interface
 
-We provide an interface to interact with behavior model or implement your own. 
+We provide an interface to interact with behavior model or implement your own. To implement your own driver model you can create a type that inherits from the abstract type `DriverModel`. Then you can implement the following methods:
 
+```@docs
+    DriverModel{DriveAction}
+    get_name(::DriverModel)
+    action_type(::DriverModel{A}) where A
+    set_desired_speed!(model::DriverModel, v_des::Float64)
+    reset_hidden_state!(model::DriverModel)
+    observe!(model::DriverModel, scene::EntityFrame{S,D,I}, roadway::R, egoid::Integer) where {S,D,I,R}
+    Base.rand(model::DriverModel)
+```
+
+`observe!` and `rand` are usually the most important methods to implement. `observe!` sets the model state in a given situation and `rand` allows to sample an action from the model.
 
 
 ## Available Behaviors
@@ -28,6 +39,10 @@ We provide an interface to interact with behavior model or implement your own.
     SidewalkPedestrianModel
 ```
 
+```@docs 
+    StaticDriver
+```
+
 ## Lane change helper functions
 These are not standalone driver models but are used by the driver models to do
 lane changing and lateral control.

src/agent-definitions/agent_definitions.jl

@@ -1,3 +1,8 @@
+"""
+    AbstractAgentDefinition
+An Agent definition represents static parameters characterizing an agent, 
+such as its physical dimensions.
+"""
 abstract type AbstractAgentDefinition end
 
 """
@@ -75,6 +80,11 @@ end
     BicycleModel
     BicycleModel(def::VehicleDef; a::Float64 = 1.5, b::Float64 = 1.5)
 Vehicle definition representing the bicycle model
+
+# Fields 
+- `def::VehicleDef`
+- `a::Float64` distance between cg and front axle [m]
+- `b::Float64` distance between cg and rear axle [m]
 """
 struct BicycleModel <: AbstractAgentDefinition
     def::VehicleDef

src/behaviors/interface.jl

@@ -1,11 +1,51 @@
+"""
+    DriverModel{DriveAction}
+A DriverModel represents a specific driving behavior. 
+It specifies the action taken by the agent at a given scene.
+The ation will be of type `DriveAction`.
+It can be interpreted as a distribution, the likelihood of taking a certain action 
+in a given scene. 
+The DriverModel type is an abstract type! Custom driver models should inherit from it.
+"""
 abstract type DriverModel{DriveAction} end
 
+"""
+    get_name(::DriverModel)
+returns the name of the driver model
+"""
 get_name(::DriverModel) = "???"
+
+"""
+    action_type(::DriverModel{A}) where {A}
+returns the type of the actions that are sampled from the model
+"""
 action_type(::DriverModel{A}) where {A} = A
+
+"""
+    set_desired_speed!(model::DriverModel, v_des::Float64)
+Sets a desired speed. It does nothing by default. 
+This method is relevant for models like IDM where the vehicle tracks a nominal speed.
+"""
 set_desired_speed!(model::DriverModel, v_des::Float64) = model # do nothing by default
+
+"""
+    reset_hidden_state!(model::DriverModel)
+Resets the hidden states of the model. It does nothing by default
+"""
 reset_hidden_state!(model::DriverModel) = model # do nothing by default
+
+"""
+    observe!(model::DriverModel, scene::EntityFrame{S,D,I}, roadway::R, egoid::Integer) where {S,D,I,R}
+Observes the scene and updates the model states accordingly. It does nothing by default.
+"""
 observe!(model::DriverModel, scene::EntityFrame{S,D,I}, roadway::R, egoid::Integer) where {S,D,I,R} = model  # do nothing by default
+
+"""
+    rand(model::DriverModel)
+Samples an action from the model.
+"""
 Base.rand(model::DriverModel) = error("rand not implemented for model $model")
+
 Distributions.pdf(model::DriverModel{A}, a::A) where {A} = error("pdf not implemented for model $model")
 Distributions.logpdf(model::DriverModel{A}, a::A) where {A} = error("logpdf not implemented for model $model")
 
@@ -45,6 +85,15 @@ end
 
 ####
 
+"""
+    StaticDriver{A,P<:ContinuousMultivariateDistribution} <: DriverModel{A}
+
+A driver model where actions are always sampled by the same distribution specified 
+by the field `distribution`.
+
+# Fields
+- `distribution::P`
+"""
 struct StaticDriver{A,P<:ContinuousMultivariateDistribution} <: DriverModel{A}
     distribution::P
 end