add docstring comments

Author: baggepinnen

lib/ControlSystemsBase/src/discrete.jl

@@ -195,7 +195,7 @@ Ref: "Discrete-time Solutions to the Continuous-time
 Differential Lyapunov Equation With Applications to Kalman Filtering", 
 Patrik Axelsson and Fredrik Gustafsson
 
-On singular covariance matrices: The traditional double integrator with covariance matrix `Q = diagm([0,σ²])` can not be sampled with this method. Instead, the input matrix ("Cholesky factor") of `Q` must be manually kept track of, e.g., the noise of variance `σ²` enters like `N = [0, 1]` which is sampled using ZoH and becomes `Nd = [1/2 Ts^2; Ts]` which results in the covariance matrix `σ² * Nd * Nd'`. 
+**On singular covariance matrices:** The traditional double integrator with covariance matrix `Qc = diagm([0,σ²])` warrants special consideration since it is rank-deficient, i.e., it indicates that there is a single source of randomness only, despite the presence of two state variables. If we assume that the noise is piecewise constant, we can use the input matrix ("Cholesky factor") of `Qc`, e.g., the noise of variance `σ²` enters like `N = [0, 1]` which is sampled using ZoH and becomes `Nd = [Ts^2 / 2; Ts]` which results in the covariance matrix `σ² * Nd * Nd'`. If we assume that the noise is a continuous-time white noise process, the discretized covariance matrix is full rank and can be computed by `c2d(sys::StateSpace{Continuous}, Qc, Ts)`. In some applications, a rank-1 approximation to this matrix is favored. In such situation, a good rank-1 approximation to this matrix is obtained by `σ² * Nd * Nd' ./ Ts`. This has the benefit of being both low rank, and produce covariance dynamics that are approximately invariant to the choice of sample interval. If the ZoH assumption is made, the covariance matrix is rank 1 but the covariance dynamics are not invariant to the choice of sample interval.`
 
 # Example:
 The following example designs a continuous-time LQR controller for a resonant system. This is simulated with OrdinaryDiffEq to allow the ODE integrator to also integrate the continuous-time LQR cost (the cost is added as an additional state variable). We then discretize both the system and the cost matrices and simulate the same thing. The discretization of an LQR contorller in this way is sometimes refered to as `lqrd`.

lib/ControlSystemsBase/src/matrix_comps.jl

@@ -124,6 +124,8 @@ Compute the observability matrix with `n` rows for the system described by `(A,
 Note that checking for observability by computing the rank from `obsv` is
 not the most numerically accurate way, a better method is checking if
 `gram(sys, :o)` is positive definite or to call the function [`observability`](@ref).
+
+The unobservable subspace is `nullspace(obsv(A, C))`, initial conditions in this subspace produce a zero response.
 """
 function obsv(A::AbstractMatrix, C::AbstractMatrix, n::Int = size(A,1))
     T = promote_type(eltype(A), eltype(C))
@@ -151,6 +153,8 @@ Compute the controllability matrix for the system described by `(A, B)` or
 Note that checking for controllability by computing the rank from
 `ctrb` is not the most numerically accurate way, a better method is
 checking if `gram(sys, :c)` is positive definite or to call the function [`controllability`](@ref).
+
+The controllable subspace is given by the range of this matrix, and the uncontrollable subspace is `nullspace(ctrb(A, B)') (note the transpose)`.
 """
 function ctrb(A::AbstractMatrix, B::AbstractVecOrMat)
     T = promote_type(eltype(A), eltype(B))
@@ -226,7 +230,10 @@ Calculate the stationary covariance `P = E[y(t)y(t)']` of the output `y` of a
 
 Remark: If `sys` is unstable then the resulting covariance is a matrix of `Inf`s.
 Entries corresponding to direct feedthrough (D*W*D' .!= 0) will equal `Inf`
-for continuous-time systems."""
+for continuous-time systems.
+    
+See also [`innovation_form`](@ref).
+"""
 function covar(sys::AbstractStateSpace, W)
     (A, B, C, D) = ssdata(sys)
     if !isa(W, UniformScaling) && (size(B,2) != size(W, 1) || size(W, 1) != size(W, 2))