diff --git a/index.rst b/index.rst index cbbdeb8..6cfdd3f 100644 --- a/index.rst +++ b/index.rst @@ -108,8 +108,13 @@ Component documentation :maxdepth: 1 score/component_example/docs/index - score/component_example/docs/architecture/component_architecture_template - score/component_example/docs/detailed_design/detailed_design_example + score/component_example/docs/architecture/index + score/component_example/docs/detailed_design/index + score/component_example/docs/requirements/index + score/component_example/docs/safety_analysis/dfa + score/component_example/docs/safety_analysis/fmea + score/component_example/docs/safety_analysis/aou_requirements_template + score/component_example/docs/component_classification Examples -------- diff --git a/score/component_example/docs/architecture/index.rst b/score/component_example/docs/architecture/index.rst index c2b25d0..0965f3e 100644 --- a/score/component_example/docs/architecture/index.rst +++ b/score/component_example/docs/architecture/index.rst @@ -141,3 +141,22 @@ Internal Components - Replace the example content by the real content (according to :need:`gd_guidl__arch_design`) - Set the status to valid and start the review/merge process + +Component Architecture Template +------------------------------- + + A component architecture template is available to be used as a starting point for the documentation of the component architecture. It includes the main sections and example content to be adapted according to the real component architecture. + +.. toctree:: + + component_architecture_template + + +Architecture Checklist +---------------------- + +See following architecture inspection checklist for verification of the architecture. + +.. toctree:: + + chklst_arc_inspection diff --git a/score/component_example/docs/detailed_design/detailed_design_example.rst b/score/component_example/docs/detailed_design/detailed_design_example.rst index 26670f3..57c3146 100644 --- a/score/component_example/docs/detailed_design/detailed_design_example.rst +++ b/score/component_example/docs/detailed_design/detailed_design_example.rst @@ -25,53 +25,18 @@ Description Static Diagrams for Unit Interactions ------------------------------------- -.. dd_sta:: dd example static - :id: dd_sta__example_feature__approver - :security: NO - :safety: ASIL_B - :status: valid - :implements: comp_req__example_feature__example_req - :satisfies: comp_arc_sta__mod_temp_component_name__sv - .. uml:: dd_example_ex_sta.puml -Dynamic Diagrams for Unit Interactions --------------------------------------- - -.. dd_dyn:: dd example dynamic - :id: dd_dyn__example_feature__dynamic - :security: NO - :safety: ASIL_B - :status: valid - :implements: comp_req__example_feature__example_req - :satisfies: comp_arc_sta__mod_temp_component_name__sv +Dynamic Diagrams for Unit Interactions (optional) +-------------------------------------------------- .. uml:: dd_example_ex_dyn.puml Units within the Component -------------------------- -From here onwards the needs are defined in the source code and will be automatically generated and linked via doxygen. - -SW Unit -******* - -The unit description is generated from the source code and linked with -the need ID sw_unit__example_feature__unit1. - -Interface -********* - -The interface description is generated from the source code and linked with -the need ID sw_unit_int__example_feature__u1_i1. - -SW Unit -******* - -The unit description is generated from the source code and linked with -the need ID sw_unit__example_feature__unit2. -Interface -********* +The units are defined in the source code. The relationship between a unit and the +component is established implicitly through the file path. -The interface description is generated from the source code and linked with -the need ID sw_unit_int__example_feature__u2_i2. +- unit1: implements the main logic (see source code for details) +- unit2: injected into unit1 via dependency injection for testability diff --git a/score/component_example/docs/detailed_design/index.rst b/score/component_example/docs/detailed_design/index.rst index 55e4ba4..0a18bcb 100644 --- a/score/component_example/docs/detailed_design/index.rst +++ b/score/component_example/docs/detailed_design/index.rst @@ -52,107 +52,48 @@ Rationale Behind Decomposition into Units Static Diagrams for Unit Interactions ------------------------------------- -.. 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 Diagrams for Unit Interactions --------------------------------------- -.. 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 --------------------------- - -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 .... +A static view provides an overview of the units and their relationships using +UML 2.0 notations (e.g. class diagrams, component diagrams). Use ``.. uml::`` +or ``.. image::`` directives to include the diagram. -In your source file, any programming language, here with C++: +Dynamic Diagrams for Unit Interactions (optional) +-------------------------------------------------- -.. code-block:: cpp +A dynamic view illustrates how the units within a component interact over their +interfaces to fulfill a specific use case or functionality. It is optional when the +component's behaviour is straightforward and can be understood from the static view +and interface documentation alone. - # need-Id: sw_unit__<Component>__<title> - class <class name> { - public: +Use standard UML behavioural diagrams (sequence diagrams, state machine diagrams) +with ``.. uml::`` or ``.. image::`` directives. - }; - -Interface View --------------- - -In your rst file: - -.. code-block:: rst +Units within the Component +-------------------------- - .. 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> +The relationship between a unit and its parent component is established implicitly +through the file path. Each component has its own directory, and units residing +within that directory belong to it. The unit's attributes and behaviour are documented +in the source code itself. A separate static diagram per unit is not required. - This implements the .... +Interface documentation of a software unit is part of the source code (e.g. public +API headers, trait definitions, or documented function signatures). -In your source file, any programming language, here with C++: +Inspection Checklist +-------------------- -.. code-block:: cpp +The checklist for verification of the detailed design inspection can be found here: - # need-Id: sw_unit__<Component>__<title> - class InterfaceDemo - { - public: - virtual ~InterfaceDemo() {} - virtual void OverrideMe() = 0; - }; +.. toctree:: -- For cpp using doxygen comments + chklst_impl_inspection -.. 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 - */ +Detail design example +--------------------- -- For rust +An example of documenting detailed design can be found in: -.. code-block:: rust + .. toctree:: - //! .. 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 .... + detailed_design_example diff --git a/score/component_example/docs/index.rst b/score/component_example/docs/index.rst index 5d17b2d..a4ad725 100644 --- a/score/component_example/docs/index.rst +++ b/score/component_example/docs/index.rst @@ -149,17 +149,3 @@ Footnotes ========= [A collection of footnotes cited in the CR, and a place to list non-inline hyperlink targets.] - -.. toctree:: - :hidden: - - architecture/index.rst - architecture/chklst_arc_inspection.rst - component_classification.rst - detailed_design/index.rst - detailed_design/chklst_impl_inspection.rst - requirements/index.rst - requirements/chklst_req_inspection.rst - safety_analysis/fmea.rst - safety_analysis/dfa.rst - safety_analysis/aou_requirements_template.rst diff --git a/score/component_example/docs/requirements/index.rst b/score/component_example/docs/requirements/index.rst index 1647e57..c1928bd 100644 --- a/score/component_example/docs/requirements/index.rst +++ b/score/component_example/docs/requirements/index.rst @@ -99,3 +99,13 @@ Hints .. needextend:: "component_name" in id :+tags: component_name + +Requirements checklist +---------------------- + +See following requirements inspection checklist for verification of the requirements. + +.. toctree:: + :hidden: + + chklst_req_inspection