diff --git a/process/process_areas/implementation/implementation_concept.rst b/process/process_areas/implementation/implementation_concept.rst index 1a6ee8f04f..837f846c32 100644 --- a/process/process_areas/implementation/implementation_concept.rst +++ b/process/process_areas/implementation/implementation_concept.rst @@ -26,10 +26,10 @@ both the requirements of ISO26262 Part-6 Chapter 8+9 and ASPICE SWE 3+4. Inputs ****** -#. ISO 26262 Part-6 Chapter 8+9 -#. ASPICE SWE 3+4 -#. Component Requirements :need:`wp__requirements_comp` and Architecture :need:`wp__component_arch` -#. Software Development Plan :need:`gd_temp__software_development_plan` +#. ISO 26262 Part-6 Chapter 8+9 +#. ASPICE SWE 3+4 +#. Component Requirements :need:`wp__requirements_comp` and Architecture :need:`wp__component_arch` +#. Software Development Plan :need:`gd_temp__software_development_plan` Outputs ******* @@ -44,9 +44,9 @@ Following the **Detailed Design Template** :need:`gd_temp__detailed_design`, we **design decisions** and **constraints** that guide the decomposition of the component into multiple units. These decisions should be made based on the following ideas: -- **Design principles** -- **Design patterns** -- **Testability strategies** +- **Design principles** +- **Design patterns** +- **Testability strategies** The goal is to ensure that the decomposition supports **reusability** , **maintainability**, **scalability**, **extensibility** and **ease of testing**. @@ -54,25 +54,30 @@ The goal is to ensure that the decomposition supports **reusability** , **mainta The detailed design and implementation should follow an **iterative approach**, allowing for continuous improvements in quality through multiple cycles of refinement. -Specification of Detailed Design --------------------------------- +Definition of a Unit +-------------------- A **unit** is a **granular, independent entity** of a component that can be **tested separately** during the unit testing phase. Each unit represents a **self-contained functionality** and is derived from the decomposition of a component. -**Draft: Characteristics of a Unit** +**Characteristics of a Unit** -- **Independent** – Can be tested in isolation. -- **Granular** – Represents a small, well-defined part of the system. -- **Relational** – Has associations with other units, defined using **UML 2.0 notations** such as - aggregation, composition, and generalization. +- **Independent** – Can be tested in isolation. +- **Granular** – Represents a small, well-defined part of the system. +- **Relational** – Has associations with other units, defined using **UML 2.0 notations** such as + aggregation, composition, and generalization. -**Units in UML Diagrams** +**Examples:** +The definition of a unit depends on the used programming language. Examples for a unit are +a source file, a definition file (e.g. c++ header), classes, structs, and functions. +This list is not complete or exclusive. -- For **Rust development**, a **unit** is modeled using a **combination of `struct` and `trait`**, - as Rust does not have traditional classes. +**Units in UML Diagrams** +- **C++ development** Each **class** can be considered a **unit** in the design. +- For **Rust development**, a **unit** is modeled using a **combination of `struct` and `trait`**, + as Rust does not have traditional classes. Static View ``````````` @@ -80,12 +85,12 @@ The **static view** represents the **units** and their relationships using **UML such as **aggregation, composition, and generalization**. This is depicted through **UML structural diagrams**, including: -- **Class Diagrams** – Define **classes, attributes, methods, and relationships** (e.g., inheritance, associations, dependencies). - Each **class** can be considered a **unit** in the design. -- **Rust Development Approach** – Instead of traditional classes, **Rust uses `struct` and `trait` - combinations** to represent **units** in UML diagrams. +- **Class Diagrams** – Define **classes, attributes, methods, and relationships** (e.g., inheritance, associations, dependencies). + Each **class** can be considered a **unit** in the design. +- **Rust Development Approach** – Instead of traditional classes, **Rust uses `struct` and `trait` + combinations** to represent **units** in UML diagrams. -This view focuses **only on units and their relationships**. +This view focuses **units, the interfaces and their relationships**. Details such as **attributes and interfaces** are documented under the **Units within the Component section** (refer to the template for details). @@ -93,9 +98,23 @@ Note that the detailed design may not be complete in the way that it covers ever These not covered parts may contain implementation detail and should not be needed to understand the the detailed design. +.. code-block:: rst + + .. dd_sta:: + :id: dd_sta__<Component>__<Title> + :security: <YES|NO> + :safety: <QM|ASIL_B> + :status: <valid|invalid> + :implements: <link to component requirement id> + :satisfies: <link to component architecture id> + :belongs_to: <link to component id> + :includes: <link to sw_unit id>, <link to sw_unit interface id> + + .. needarch:: or .. image:: <link to drawio image> + Dynamic View ```````````` -The **dynamic view** illustrates how the **units** interact with each other to fulfill a specific +The **dynamic view** illustrates how the **units** interact with each other over **interfaces** to fulfill a specific **use case** or **functionality**. This view captures the **behavioral aspects** of the component as it executes. It is represented using **UML behavioral diagrams**, including: @@ -108,6 +127,20 @@ These diagrams are essential for understanding the **dynamic behavior** of the c units collaborate to perform tasks. But this also means that if the dynamic behaviour is simple it does not require a dynamic diagram at all (similar to the rules depicted in :need:`gd_guidl__arch_design`). +.. code-block:: rst + + .. dd_dyn:: <Title> + :id: dd_dyn__<Component>__<Title> + :security: <YES|NO> + :safety: <QM|ASIL_B> + :status: <valid|invalid> + :implements: <link to component requirement id> + :satisfies: <link to component architecture id> + :belongs_to: <link to component id> + :includes: <link to sw_unit id>, <link to sw_unit interface id> + + .. needarch:: or .. image:: <link to drawio image> + Units within the Component -------------------------- @@ -115,56 +148,117 @@ For each unit it will have a id and the interfaces are shown in the interface vi The description of unit and its attributes can be seen in the code documentation. For this we use the tracing to the documentation generated from the code comments. -We link the unit id to the comments in the code like - +We link the unit id to the comments in the code like: + +- Maintain your units in rst files and link them to the source code + + Use `score_source_code_linker` from `docs-as-code` repo with + `user docu <https://eclipse-score.github.io/docs-as-code/main/how-to/source_to_doc_links.html>`__. + + In your rst file: + + .. code-block:: rst + + .. sw_unit:: cpp unit + :id: sw_unit__<Component>__<title> + :belongs_to: <link to component id> + + This implements the .... + + In your source file, any programming language, here with C++: -For cpp using doxygen style comments- + .. code-block:: cpp -.. code-block:: cpp + # need-Id: sw_unit__<Component>__<title> + class <class name> { + public: - /** - * @rst - * .. sw_unit:: cpp unit - * :id: sw_unit__<Feature>__<title> - * - * This implements the .... - * @endrst - */ + }; -for rust - +- For cpp using doxygen style comments -.. code-block:: rust + .. code-block:: cpp - //! .. sw_unit:: rust unit - //! :id: sw_unit__<Feature>__<title> - //! - //! This implements the .... + /** + * @rst + * .. sw_unit:: cpp unit + * :id: sw_unit__<Component>__<title> + * :belongs_to: <link to component id> + * + * This implements the .... + * @endrst + */ + +- for rust + + .. code-block:: rust + + //! .. sw_unit:: rust unit + //! :id: sw_unit__<Component>__<title> + //! :belongs_to: <link to component id> + //! + //! This implements the .... Interface View `````````````` -For every unit, it should show the interface provided by that unit. For each unit and corresponding -interface, there shall be an implementation and documentation which is generated for the implementation -will have the units description and the interface. According the template the attributes shall be -filled and corresponding element is shown in the documentation generated form the implementation. +For every unit, the Interface View should display the interfaces provided by that unit. +For each unit and its corresponding interfaces, an implementation and documentation must +be created. + +The following section provides templates for defining needs within the source code: + +- Maintain your units in rst files and link them to the source code + + Use `score_source_code_linker` from `docs-as-code` repo with + `user docu <https://eclipse-score.github.io/docs-as-code/main/how-to/source_to_doc_links.html>`__. + + In your rst file: + + .. code-block:: rst + + .. sw_unit_int:: <here InterfaceDemo - change it> + :id: sw_unit_int__<Component>__<title> + :belongs_to: <link to sw_unit id> + :implements: <real_arc_int, real_arc_int_op> + + This implements the .... + + In your source file, any programming language, here with C++: + + .. code-block:: cpp + + # need-Id: sw_unit__<Component>__<title> + class InterfaceDemo + { + public: + virtual ~InterfaceDemo() {} + virtual void OverrideMe() = 0; + }; + +- For cpp using doxygen comments -For cpp using doxygen comments- + .. code-block:: cpp -.. code-block:: cpp + /** + * @rst + * .. sw_unit_int:: cpp unit + * :id: sw_unit_int__<Component>__<title> + * :belongs_to: <link to sw_unit id> + * :implements: <real_arc_int, real_arc_int_op> + * + * This implements the .... + * @endrst + */ - /** - * @rst - * .. sw_unit_int:: cpp unit - * :id: sw_unit_int__<Feature>__<title> - * - * This implements the .... - * @endrst - */ +- For rust -For rust - + .. code-block:: rust -.. code-block:: rust + //! .. sw_unit_int:: rust unit + //! :id: sw_unit_int__<Component>__<title> + //! :belongs_to: <link to sw_unit id> + //! :implements: <real_arc_int, real_arc_int_op> + //! + //! This implements the .... - //! .. sw_unit_int:: rust unit - //! :id: sw_unit_int__<Feature>__<title> - //! - //! This implements the ....