Doc work

examples/beam_combine_test.rs

@@ -6,8 +6,8 @@ use opossum::{
     error::OpossumError,
     lightdata::{DataEnergy, LightData},
     nodes::{BeamSplitter, Detector, FilterType, IdealFilter, Source},
-    OpticScenery,
     spectrum::{create_he_ne_spectrum, create_nd_glass_spectrum, Spectrum},
+    OpticScenery,
 };
 
 fn main() -> Result<(), OpossumError> {

examples/filter_test.rs

@@ -6,8 +6,8 @@ use opossum::{
     error::OpossumError,
     lightdata::{DataEnergy, LightData},
     nodes::{BeamSplitter, Detector, FilterType, IdealFilter, Source},
-    OpticScenery,
     spectrum::{create_he_ne_spectrum, Spectrum},
+    OpticScenery,
 };
 
 fn main() -> Result<(), OpossumError> {

examples/group_test.rs

@@ -7,8 +7,8 @@ use opossum::{
     lightdata::{DataEnergy, LightData},
     nodes::{BeamSplitter, Detector, Dummy, NodeGroup, Source},
     optic_node::OpticNode,
-    OpticScenery,
     spectrum::create_he_ne_spectrum,
+    OpticScenery,
 };
 
 fn main() -> Result<(), OpossumError> {

src/analyzer.rs

+//! Optical Analyzers
 use crate::{error::OpossumError, optic_scenery::OpticScenery};
 
 type Result<T> = std::result::Result<T, OpossumError>;

src/error.rs

-//! Opossum specfic error structure
+//! Opossum specfic error structures
 use std::{error::Error, fmt::Display};
 
+/// Errors that can be returned by various OPOSSUM functions.
 #[derive(Debug, Clone)]
 pub enum OpossumError {
     /// error while setting up an `OpticScenery`
     OpticScenery(String),
     /// error while setting up an `OpticGroup`. The reasons are similar to [`OpossumError::OpticScenery`]
     OpticGroup(String),
+    /// (mostly internal) errors while dealing with optical ports.
     OpticPort(String),
     /// mostly runtime errors occuring during the analysis of a scenery
     Analysis(String),

src/lib.rs

-//! This is the documentation for the OPOSSUM software package. OPOSSUM stands for OPen-source Optics Simulation Software and Unified Modeller.
+//! This is the documentation for the **OPOSSUM** software package. **OPOSSUM** stands for
+//! **Op**en-source **O**ptics **S**imulation **S**oftware and **U**nified **M**odeller.
 //!
 mod light;
 pub mod lightdata;
@@ -17,4 +18,4 @@ pub mod error;
 
 pub mod spectrum;
 
-pub use optic_scenery::OpticScenery;
\ No newline at end of file
+pub use optic_scenery::OpticScenery;

src/light.rs

 //! Data structure for the graph edges.
-//! 
+//!
 //! [`Light`] represents the information / data flowing from one node to another node. It contains information about
 //! the respective source an target port names this edge connects as well as the actual light information (stored as
 //! [`LightData`]).

src/lightdata.rs

@@ -8,7 +8,7 @@ use crate::spectrum::Spectrum;
 /// Data structure defining the light properties. The actuals data type used depends on the
 /// [`AnalyzerType`](crate::analyzer::AnalyzerType). For example, an energy analysis ([`LightData::Energy`]) only
 /// contains a [`Spectrum`] information, while a geometric analysis ([`LightData::Geometric]) constains a set of optical
-/// ray data. 
+/// ray data.
 #[derive(Debug, Clone)]
 pub enum LightData {
     /// data type used for energy analysis.

src/nodes/beam_splitter.rs

@@ -13,6 +13,14 @@ type Result<T> = std::result::Result<T, OpossumError>;
 
 #[derive(Debug)]
 /// An ideal beamsplitter node with a given splitting ratio.
+///
+/// ## Optical Ports
+///   - Inputs
+///     - `input1`
+///     - `input2`
+///   - Outputs
+///     - `out1_trans1_refl2`
+///     - `out2_trans2_refl1`
 pub struct BeamSplitter {
     ratio: f64,
 }

src/nodes/detector.rs

@@ -12,6 +12,12 @@ type Result<T> = std::result::Result<T, OpossumError>;
 /// This node represents an universal detector.
 ///
 /// Any [`LightData`] coming in will be stored internally for later display / export. So far it only has one input (in1).
+///
+/// ## Optical Ports
+///   - Inputs
+///     - `in1`
+///   - Outputs
+///     - none
 pub struct Detector {
     light_data: Option<LightData>,
 }

src/nodes/dummy.rs

@@ -8,10 +8,16 @@ use crate::optic_ports::OpticPorts;
 type Result<T> = std::result::Result<T, OpossumError>;
 
 #[derive(Debug)]
-/// A fake / dummy component without any functions.
+/// A fake / dummy component without any optical functionality.
 ///
 /// Any [`LightResult`] is directly forwarded without any modification. It is mainly used for
 /// development and debugging purposes.
+///
+/// ## Optical Ports
+///   - Inputs
+///     - `front`
+///   - Outputs
+///     - `rear`
 pub struct Dummy;
 
 impl Optical for Dummy {

src/nodes/group.rs

@@ -20,7 +20,14 @@ type Result<T> = std::result::Result<T, OpossumError>;
 #[derive(Default, Debug, Clone)]
 /// A node that represents a group of other [`OpticNode`]s arranges in a subgraph.
 ///
-/// All unconnected input and output ports of this subgraph form the ports of this [`NodeGroup`].
+/// All unconnected input and output ports of this subgraph could be used as ports of
+/// this [`NodeGroup`]. For this, port mapping is neccessary (see below).
+///
+/// ## Optical Ports
+///   - Inputs
+///     - defined by [`map_input_port`](NodeGroup::map_input_port()) function.
+///   - Outputs
+///     - defined by [`map_output_port`](NodeGroup::map_output_port()) function.
 pub struct NodeGroup {
     g: DiGraph<Rc<RefCell<OpticNode>>, Light>,
     input_port_map: HashMap<String, (NodeIndex, String)>,

src/nodes/ideal_filter.rs

@@ -18,6 +18,12 @@ pub enum FilterType {
 }
 #[derive(Debug)]
 /// An ideal filter with given transmission or optical density.
+///
+/// ## Optical Ports
+///   - Inputs
+///     - `front`
+///   - Outputs
+///     - `rear`
 pub struct IdealFilter {
     filter_type: FilterType,
 }

src/nodes/reference.rs

@@ -12,6 +12,12 @@ type Result<T> = std::result::Result<T, OpossumError>;
 /// A virtual component referring to another existing component.
 ///
 /// This node type is necessary in order to model resonators (loops) or double-pass systems.
+///
+/// ## Optical Ports
+///   - Inputs
+///     - input ports of the referenced [`OpticNode`]
+///   - Outputs
+///     - output ports of the referenced [`OpticNode`]
 pub struct NodeReference {
     reference: Weak<RefCell<OpticNode>>,
 }

src/nodes/source.rs

@@ -13,6 +13,12 @@ type Result<T> = std::result::Result<T, OpossumError>;
 /// This node represents a source of light.
 ///
 /// Hence it has only one output port (out1) and no input ports. Source nodes usually are the first nodes of an optic scenery.
+///
+/// ## Optical Ports
+///   - Inputs
+///     - none
+///   - Outputs
+///     - `out1`
 #[derive(Default)]
 pub struct Source {
     light_data: Option<LightData>,

src/optic_node.rs

@@ -99,7 +99,7 @@ pub trait Optical {
         OpticPorts::default()
     }
     /// Perform an analysis of this element. The type of analysis is given by an [`AnalyzerType`].
-    /// 
+    ///
     /// This function is normally only called by [`OpticScenery::analyze()`](crate::optic_scenery::OpticScenery::analyze()).
     ///
     /// # Errors

src/optic_scenery.rs

@@ -16,7 +16,7 @@ use petgraph::Direction::{Incoming, Outgoing};
 type Result<T> = std::result::Result<T, OpossumError>;
 
 /// Overall optical model and additional metatdata.
-/// 
+///
 /// All optical elements ([`OpticNode`]s) have to be added to this structure in order
 /// to be considered for an analysis.
 #[derive(Default, Debug, Clone)]