Merge pull request #41 from AayushSabharwal/new_docstrings

Electrical Component Docstrings

Author: ChrisRackauckas

docs/src/API/electrical.md

@@ -8,15 +8,16 @@ CurrentModule = ModelingToolkitStandardLibrary.Electrical
 ```@docs
 Pin
 OnePort
+DigitalPin
 ```
 
 ## Analog Components
 
 ```@docs
-Capacitor
 Ground
-Inductor
 Resistor
+Capacitor
+Inductor
 IdealOpAmp
 ```
 
@@ -30,7 +31,7 @@ PowerSensor
 MultiSensor
 ```
 
-## Analogue Sources
+## Analog Sources
 
 ```@docs
 ConstantVoltage
@@ -49,4 +50,33 @@ SquareCurrent
 TriangularCurrent
 CosineCurrent
 ExpSineCurrent
+```
+
+## Digital Gates
+```@docs
+Not
+And
+Nand
+Or
+Nor
+Xor
+Xnor
+```
+
+## Digital Components
+```@docs
+HalfAdder
+FullAdder
+MUX
+DEMUX
+Encoder
+Decoder
+```
+
+## Digital Sources
+```@docs
+PulseDiff
+Set
+Reset
+Pulse
 ```

src/Electrical/Analog/ideal_components.jl

@@ -1,7 +1,13 @@
 """
-    Ground(;name)
+```julia
+function Ground(; name)
+```
 
-Ground of an electrical circuit. The potential at the ground node is zero. Every circuit must have one ground node.
+Ground node with the potential of zero and connector `g`. Every circuit must have one ground
+node.
+
+# Connectors
+- `g`
 """
 function Ground(;name)
     @named g = Pin()
@@ -10,12 +16,25 @@ function Ground(;name)
 end
 
 """
-    Resistor(;name, R=1.0)
+```julia
+function Resistor(; name, R = 1.0)
+```
+
+Creates an ideal Resistor following Ohm's Law.
+
+# States
+- `v(t)`: [`V`]
+  The voltage across the resistor, given by `p.i * R`
 
-Ideal linear electrical resistor.
+# Connectors
+- `p`
+  Positive pin
+- `n`
+  Negative pin
 
 # Parameters: 
-- `R`: [Ω] Resistance
+- `R`: [`Ω`]
+  Resistance
 """
 function Resistor(;name, R=1.0)
     @named oneport = OnePort()
@@ -28,13 +47,27 @@ function Resistor(;name, R=1.0)
 end
 
 """
-    Capacitor(;name, C=1.0, v_start=0.0) 
+```julia
+function Capacitor(; name, C = 1.0)
+```
+
+Creates an ideal Capacitor.
+
+# States
+- `v(t)`: [`V`]
+  The voltage across the capacitor, given by `D(v) ~ p.i / C`
 
-Ideal linear electrical capacitor.
+# Connectors
+- `p`
+  Positive pin
+- `n`
+  Negative pin
 
 # Parameters:
-- `C`: [F] Capacity
-- `v_start`: [V] Initial voltage of capacitor
+- `C`: [`F`]
+  Capacitance
+- `v_start`: [`V`]
+  Initial voltage of capacitor
 """
 function Capacitor(;name, C=1.0, v_start=0.0) 
     @named oneport = OnePort(;v_start=v_start)
@@ -47,13 +80,27 @@ function Capacitor(;name, C=1.0, v_start=0.0)
 end
 
 """
-    Inductor(;name, L=1.0e-6, i_start=0.0)
+```julia
+function Inductor(; name, L = 1.0)
+```
 
-Ideal linear electrical inductor.
+Creates an ideal Inductor.
+
+# States
+- `v(t)`: [`V`]
+  The voltage across the inductor, given by `D(p.i) ~ v / L`
+
+# Connectors
+- `p`
+  Positive pin
+- `n`
+  Negative pin
 
 # Parameters:
-- `L`: [H] Inductance
-- `i_start`: [A] Initial current through inductor
+- `L`: [`H`]
+  Inductance
+- `i_start`: [`A`]
+  Initial current through inductor
 """
 function Inductor(;name, L=1.0e-6, i_start=0.0)
     @named oneport = OnePort(;i_start=i_start)
@@ -66,11 +113,33 @@ function Inductor(;name, L=1.0e-6, i_start=0.0)
 end
 
 """
-    IdealOpAmp(;name)
+```julia
+function IdealOpAmp(; name)
+```
 
 Ideal operational amplifier (norator-nullator pair).
-The ideal OpAmp is a two-port. The left port is fixed to v1=0 and i1=0 (nullator). 
-At the right port both any voltage v2 and any current i2 are possible (norator).
+The ideal OpAmp is a two-port. The left port is fixed to `v1 = 0` and `i1 = 0` (nullator). 
+At the right port both any voltage `v2` and any current `i2` are possible (norator).
+
+# States
+- `v1(t)`: [`V`]
+  Voltage of left port
+- `v2(t)`: [`V`]
+  Voltage of right port
+- `i1(t)`: [`A`]
+  Current of left port
+- `i2(t)`: [`A`]
+  Current of right port
+
+# Connectors
+- `p1`
+  Positive pin (left port)
+- `p2`
+  Positive pin (right port)
+- `n1`
+  Negative pin (left port)
+- `n2`
+  Negative pin (right port)
 """
 function IdealOpAmp(;name)
     @named p1 = Pin()

src/Electrical/Analog/sensors.jl

@@ -1,7 +1,20 @@
 """
-    CurrentSensor(; name)
+```julia
+function CurrentSensor(; name)
+```
+
+Creates a circuit component that measures the current flowing through it. Analogous to
+an ideal ammeter.
 
-Sensor to measure the current through a branch in amperes.
+# States
+- `i(t)`: [`A`]
+  Current through the sensor
+
+# Connectors
+- `p`
+ Positive pin
+- `n`
+  Negative pin
 """
 function CurrentSensor(; name)
     @named p = Pin()
@@ -16,9 +29,19 @@ function CurrentSensor(; name)
 end
 
 """
-    PotentialSensor(; name)
+```julia
+function PotentialSensor(; name)
+```
 
-Sensor to measure the potential in volt.
+Creates a circuit component which measures the potential at a pin.
+
+# States
+- `phi(t)`: [`V`]
+  The potential at this point
+
+# Connectors
+- `p`
+  Pin at which potential is to be measured
 """
 function PotentialSensor(; name)
     @named p = Pin()
@@ -31,9 +54,22 @@ function PotentialSensor(; name)
 end
 
 """
-    VoltageSensor(; name)
+```julia
+function VoltageSensor(; name)
+```
+
+Creates a circuit component that measures the voltage across it. Analogous to
+an ideal voltmeter.
 
-Sensor to measure the potential difference between two pins in volt.
+# States
+- `v(t)`: [`V`]
+  The voltage across this component
+
+# Connectors
+- `p`
+  Positive pin
+- `n`
+  Negative pin
 """
 function VoltageSensor(; name)
     @named p = Pin()
@@ -48,9 +84,26 @@ function VoltageSensor(; name)
 end
 
 """
-    PowerSensor(; name)
+```julia
+function PowerSensor(; name)
+```
+
+Combines a [`VoltageSensor`](@ref) and a [`CurrentSensor`](@ref) to measure the power being
+consumed by a circuit.
+
+# States
+- `power(t)`: [`W`]
+  The power being consumed, given by the product of voltage and current.
 
-Sensor to measure the power in watt.
+# Connectors
+- `pc`
+  Corresponds to the `p` pin of the [`CurrentSensor`](@ref)
+- `nc`
+  Corresponds to the `n` pin of the [`CurrentSensor`](@ref)
+- `pv`
+  Corresponds to the `p` pin of the [`VoltageSensor`](@ref)
+- `nv`
+  Corresponds to the `n` pin of the [`VoltageSensor`](@ref)
 """
 function PowerSensor(; name)
     @named pc = Pin()
@@ -71,9 +124,27 @@ function PowerSensor(; name)
 end
 
 """
-    MultiSensor(; name)
+```julia
+function MultiSensor(; name)
+```
+
+Combines a [`VoltageSensor`](@ref) and a [`CurrentSensor`](@ref).
+
+# States
+- `v(t)`: [`V`]
+  The voltage across the [`VoltageSensor`](@ref)
+- `i(t)`: [`A`]
+  The current across the [`CurrentSensor`](@ref)
 
-Sensor to measure current [A], voltage [V] and power [W].
+# Connectors
+- `pc`
+  Corresponds to the `p` pin of the [`CurrentSensor`](@ref)
+- `nc`
+  Corresponds to the `n` pin of the [`CurrentSensor`](@ref)
+- `pv`
+  Corresponds to the `p` pin of the [`VoltageSensor`](@ref)
+- `nv`
+  Corresponds to the `n` pin of the [`VoltageSensor`](@ref)
 """
 function MultiSensor(; name)
     @named pc = Pin()