From 547e594d3f50682875673ee7ab0d8c3e6d6d9d7d Mon Sep 17 00:00:00 2001 From: aschemmel-git Date: Thu, 31 Jul 2025 14:52:42 +0200 Subject: [PATCH] Create draft API guideline Ref: resolves #1533 --- docs/contribute/development/api_guideline.rst | 33 +++++++++++++++++++ docs/contribute/development/index.rst | 1 + .../software_development.rst | 6 ++++ 3 files changed, 40 insertions(+) create mode 100644 docs/contribute/development/api_guideline.rst diff --git a/docs/contribute/development/api_guideline.rst b/docs/contribute/development/api_guideline.rst new file mode 100644 index 0000000000..0b110a875d --- /dev/null +++ b/docs/contribute/development/api_guideline.rst @@ -0,0 +1,33 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +Designing API +############# + +.. document:: API Guidelines + :id: doc__api_guidelines + :status: draft + +User friendly API design +======================== + +* Each public API shall support the idioms of the programming language it is written in. +* Each public API shall use core infrastructure of its programming language and accompanying standard libraries, whenever possible and meaningful. + +Error handling +============== + +* (C++) exceptions shall not be used for error handling, as these will be directly leading to an abort and thus reducing availability of the S-CORE platform. +* The best way to deal with errors is to try to resolve those component internally. If not possible the caller of the function shall be notified of the error. +* For (error) returns there is a specific library to be used in S-CORE, it is the Score::Result library which is part of the :ref:`baselibs_feature` feature. diff --git a/docs/contribute/development/index.rst b/docs/contribute/development/index.rst index 086e6be44b..b8428b2ae8 100644 --- a/docs/contribute/development/index.rst +++ b/docs/contribute/development/index.rst @@ -19,6 +19,7 @@ Development :maxdepth: 1 development_environment + api_guideline cpp/index rust/index python/index diff --git a/docs/platform_management_plan/software_development.rst b/docs/platform_management_plan/software_development.rst index 1fc54164ad..0844381797 100644 --- a/docs/platform_management_plan/software_development.rst +++ b/docs/platform_management_plan/software_development.rst @@ -66,6 +66,12 @@ Design guideline The design guideline is defined in :need:`PROCESS_doc_concept__imp__concept` and :need:`PROCESS_gd_guidl__implementation`. +API guideline +^^^^^^^^^^^^^ + +To provide the user with a consistent approach on the use of APIs, there is a guideline documented in :need:`doc__api_guidelines`, +this defines for example the error handling concept or rules to improve user experience. + Coding guideline ^^^^^^^^^^^^^^^^