docs: add reference documentations

This commit is contained in:
Johel Ernesto Guerrero Peña
2024-09-08 08:20:26 +02:00
committed by Mateusz Pusz
parent 04f128623e
commit 20d58666fe
7 changed files with 538 additions and 0 deletions

View File

@ -1,3 +1,4 @@
include: ["cmake/.cmake-format-additional_commands-jegp.cmake_modules.yaml"]
parse:
additional_commands:
add_mp_units_module:

3
.gitignore vendored
View File

@ -46,3 +46,6 @@ CMakeUserPresets.json
# Conan
*.pyc
/test_package/build/
# cxxdraft-htmlgen
docs/reference/source/

View File

@ -0,0 +1,82 @@
parse:
additional_commands:
_jegp_common_yaml_anchors:
kwargs:
PUBLIC_INTERFACE_PRIVATE: &public_interface_private
kwargs:
PUBLIC: +
INTERFACE: +
PRIVATE: +
jegp_add_standardese_sources:
pargs:
nargs: 1
flags:
- EXCLUDE_FROM_ALL
kwargs:
LIBRARIES: +
APPENDICES: +
EXTENSIONS: +
CHECKED: 1
PDF: &standardese_pdf
pargs:
flags:
- EXCLUDE_FROM_MAIN
kwargs:
PATH: 1
HTML:
<<: *standardese_pdf
kwargs:
SECTION_FILE_STYLE: 1
LATEX_REGEX_REPLACE: +
HTML_REGEX_REPLACE: +
jegp_add_module:
pargs: &jegp_add_module_pargs
nargs: 1
flags:
- IMPORTABLE_HEADER
kwargs:
SOURCES: +
COMPILE_OPTIONS: *public_interface_private
LINK_LIBRARIES: *public_interface_private
jegp_cpp_module:
pargs: *jegp_add_module_pargs
jegp_target_link_header_units:
pargs:
nargs: 1+
jegp_cpp2_target_sources:
pargs:
nargs: 1
kwargs:
JEGP_FILE_SET_KWARGS: &file_set
kwargs:
FILE_SET: 1
TYPE: 1
BASE_DIRS: +
FILES: +
PUBLIC: *file_set
INTERFACE: *file_set
PRIVATE: *file_set
jegp_add_headers_test:
pargs:
nargs: 1+
kwargs:
PRIVATE_REGEXES: +
jegp_add_test:
pargs:
nargs: 1+
flags:
- COMPILE_ONLY
kwargs:
TYPE: 1
SOURCES: +
COMPILE_OPTIONS: +
LINK_LIBRARIES: +
jegp_add_build_error:
pargs:
nargs: 1+
kwargs:
AS: 1
TYPE: 1
SOURCE: 1
COMPILE_OPTIONS: +
LINK_LIBRARIES: +

View File

@ -0,0 +1,41 @@
cmake_minimum_required(VERSION 3.24.0)
project(mp-units_reference_documentations LANGUAGES NONE)
include(JEGPAddStandardeseSources)
set(pdf_title "mp-units Library")
set(page_license "MIT License")
set(first_library_chapter "qties")
set(last_library_chapter "qties")
set(cover_title "mp-units Library Reference Documentations")
set(reply_to "\\href{${PROJECT_HOMEPAGE_URL}/discussions}{Discussions}, \\href{${PROJECT_HOMEPAGE_URL}/issues}{issues}")
jegp_add_standardese_sources(
mp-units_reference_documentations
LIBRARIES intro quantities
EXTENSIONS macros_extensions
CHECKED TRUE
PDF PATH "mp-units.pdf" #[[EXCLUDE_FROM_MAIN]]
HTML PATH "mp-units.html" #[[EXCLUDE_FROM_MAIN]]
SECTION_FILE_STYLE "WithExtension"
LATEX_REGEX_REPLACE
# Latex commands.
[[\\href{([^}]+)}{([^}]+)};HREF(\1)(\2)]]
# Macros extensions.
[[\\refcpp{([^}]+)};REFCPP(\1)]]
[[\\irefcpp{([^}]+)};~(REFCPP(\1))]]
[[\\refcppx{([^}]+)}{([^}]+)};REFCPPX(\1)(\2)]]
[[\\irefcppx{([^}]+)}{([^}]+)};~(REFCPPX(\1)(\2))]]
[[\\refiev{([^}]+)};REFIEV(\1)]]
[[\\irefiev{([^}]+)};~(REFIEV(\1))]]
# Main matter and annexes.
[[\\\"{o};ö]]
HTML_REGEX_REPLACE
# Latex commands.
[[HREF\(([^)]+)\)\(([^)]+)\);<a href="\1">\2</a>]]
# Macros extensions.
[[REFCPP\(([^)]+)\);<a href="https://wg21.link/\1">ISOCPP, [\1]</a>]]
[[REFCPPX\(([^)]+)\)\(([^)]+)\);<a href="https://wg21.link/\1\2">ISOCPP, [\1]</a>]] #
[[ISOCPP;N4971]]
[[REFIEV\(([^)]+)\);<a href="https://www.electropedia.org/iev/iev.nsf/display?openform&ievref=\1">IEC 60050, \1</a>]]
# Main matter and annexes.
)

134
docs/reference/intro.tex Normal file
View File

@ -0,0 +1,134 @@
%!TEX root = std.tex
\rSec0[scope]{Scope}
\pnum
\indextext{scope|(}%
This document describes the contents of the \defn{mp-units library}.
\indextext{scope|)}
\rSec0[refs]{References}
\pnum
\indextext{references|(}%
The following documents are referred to in the text
in such a way that some or all of their content
constitutes requirements of this document.
For dated references, only the edition cited applies.
For undated references,
the latest edition of the referenced document
(including any amendments) applies.
\begin{itemize}
\item
IEC 60050-102:2007/AMD3:2021,
\doccite{Amendment 3 --- International Electrotechnical Vocabulary (IEV) ---
Part 102: Mathematics --- General concepts and linear algebra}
\item
IEC 60050-112:2010/AMD2:2020,
\doccite{Amendment 2 --- International Electrotechnical Vocabulary (IEV) ---
Part 112: Quantities and units}
\item
ISO 80000 (all parts), \doccite{Quantities and units}
\item
The \Cpp{} Standards Committee.
\IsoCpp{}: \doccite{Working Draft, Standard for Programming Language \Cpp{}}.
Edited by Thomas K\"{o}ppe.
Available from: \url{https://wg21.link/\IsoCpp{}}
\item
The \Cpp{} Standards Committee.
SD-8: \doccite{Standard Library Compatibility}.
Edited by Bryce Lelbach.
Available from: \url{https://wg21.link/SD8}
\end{itemize}
\indextext{references|)}
\rSec0[defs]{Terms and definitions}
\pnum
\indextext{definitions|(}%
For the purposes of this document,
the terms and definitions given in
IEC 60050-102:2007/AMD3:2021,
IEC 60050-112:2010/AMD2:2020,
ISO 80000-2:2019,
and
\IsoCpp{},
and the following apply.
\pnum
ISO and IEC maintain terminology databases
for use in standardization
at the following addresses:
\begin{itemize}
\item ISO Online browsing platform: available at \url{https://www.iso.org/obp}
\item IEC Electropedia: available at \url{http://www.electropedia.org}
\end{itemize}
\indextext{definitions|)}
\rSec0[spec]{Specification}
\rSec1[spec.ext]{External}
\pnum
The specification of the mp-units library subsumes
\refcpp{description}, \refcpp{requirements}, \refcpp{concepts.equality}, and SD-8,
all assumingly amended for the context of this library.
\begin{note}
This means that, non exhaustively,
\begin{itemize}
\item \tcode{::mp_units2} is a reserved namespace, and
\item
\tcode{std::vector<mp_units::\placeholdernc{type}>}
is a program-defined specialization and a library-defined specialization
from the point of view of the \Cpp{} standard library and the mp-units library, respectively.
\end{itemize}
\end{note}
\pnum
The mp-units library is not part of the \Cpp{} implementation.
\rSec1[spec.cats]{Categories}
\pnum
Detailed specifications for each of the components in the library are in
\ref{\firstlibchapter}--\ref{\lastlibchapter},
as shown in \tref{lib.cats}.
\begin{floattable}{Library categories}{lib.cats}
{ll}
\topline
\hdstyle{Clause} & \hdstyle{Category} \\ \capsep
\ref{qties} & Quantities library \\
\end{floattable}
\pnum
The quantities library\iref{qties}
describes components for dealing with quantities.
\rSec1[spec.mods]{Modules}
\pnum
The mp-units library provides the
\defnx{mp-units modules}{module!mp-units},
shown in \tref{modules}.
\begin{multicolfloattable}{mp-units modules}{modules}
{lll}
\tcode{mp_units} \\
\columnbreak
\tcode{mp_units.core} \\
\columnbreak
\tcode{mp_units.systems} \\
\end{multicolfloattable}
\rSec1[spec.reqs]{Library-wide requirements}
\rSec2[spec.res.names]{Reserved names}
\pnum
The mp-units library reserves macro names that start with
\tcode{MP_UNITS\opt{\gterm{digit-sequence}}_}.

View File

@ -0,0 +1,11 @@
\newcommand{\IsoCpp}{N4971}
%% Inline non-parenthesized C++ reference
\newcommand{\refcpp}[1]{\href{https://wg21.link/#1}{\IsoCpp{}, [#1]}}
\newcommand{\irefcpp}[1]{\nolinebreak[3] (\refcpp{#1})}
\newcommand{\refcppx}[2]{\href{https://wg21.link/#1\##2}{\IsoCpp{}, [#1]}}
\newcommand{\irefcppx}[2]{\nolinebreak[3] (\refcppx{#1}{#2})}
%% Inline IEV reference
\newcommand{\refiev}[1]{\href{https://www.electropedia.org/iev/iev.nsf/display?openform&ievref=#1}{IEC 60050, #1}}
\newcommand{\irefiev}[1]{\nolinebreak[3] (\refiev{#1})}

View File

@ -0,0 +1,266 @@
%!TEX root = std.tex
\rSec0[qties]{Quantities library}
\rSec1[qties.summary]{Summary}
\pnum
This Clause describes components for dealing with quantities,
as summarized in \tref{qties.summary}.
\begin{modularlibsumtab}{Quantities library summary}{qties.summary}
\ref{qty.helpers} & Helpers & \tcode{mp_units.core} \\
\ref{qty.traits} & Traits & \\
\ref{qty.concepts} & Concepts & \\
\ref{qty.types} & Types & \\
\ref{qty.compat} & Compatibility & \\
\ref{qty.one} & Dimension one & \\ \rowsep
\ref{qty.systems} & Systems & \tcode{mp_units.systems} \\
\ref{qty.chrono} & \tcode{std::chrono} compatibility & \\
\end{modularlibsumtab}
\rSec1[mp.units.syn]{Module \tcode{mp_units} synopsis}
\indexmodule{mp_units}%
\begin{codeblock}
export module mp_units;
export import mp_units.core;
export import mp_units.systems;
\end{codeblock}
\rSec1[mp.units.core.syn]{Module \tcode{mp_units.core} synopsis}
\indexmodule{mp_units.core}%
\begin{codeblock}
export module mp_units.core;
import std;
export namespace mp_units {
export enum class quantity_character { scalar, vector, tensor };
// \ref{qty.traits}, traits
template<typename Rep>
constexpr bool treat_as_floating_point = std::is_floating_point_v<Rep>;
template<typename Rep>
constexpr bool is_scalar =
std::is_floating_point_v<Rep> || (std::is_integral_v<Rep> && !is_same_v<Rep, bool>);
template<typename Rep>
constexpr bool is_vector = false;
template<typename Rep>
constexpr bool is_tensor = false;
template<typename Rep>
struct quantity_values;
template<typename T>
struct quantity_like_traits;
template<typename T>
struct quantity_point_like_traits;
// \ref{qty.concepts}, concepts
template<typename T>
concept @\deflibconcept{some_reference}@ = template_of(^std::remove_cvref_t<T>) == ^reference;
template<typename T>
concept representation = @\seebelownc@;
template<typename T, quantity_character Ch>
concept representation_of = @\seebelownc@;
template<typename T>
concept some_quantity_spec = @\seebelownc@;
// \ref{qty.types}, types
template<auto...>
struct quantity_spec; // \notdef
template<auto Q>
struct kind_of_; // \notdef
template<@\unspec@... Expr>
struct derived_quantity_spec;
// \ref{qty.type}, class template \tcode{quantity}
export template<@\libconcept{some_reference}@ auto R,
@\libconcept{representation_of}@<get_quantity_spec(R).character> Rep = double>
class quantity;
// \ref{qty.point.type}, class template \tcode{quantity_point}
template<@\unspec@>
class quantity_point;
}
\end{codeblock}
\rSec1[mp.units.systems.syn]{Module \tcode{mp_units.systems} synopsis}
\indexmodule{mp_units.systems}%
\begin{codeblock}
export module mp_units.systems;
export import mp_units.core;
import std;
export namespace mp_units {
}
\end{codeblock}
\rSec1[qty.helpers]{Helpers}
\begin{itemdecl}
consteval bool @\exposidnc{converts-to-base-subobject-of}@(std::meta type, std::meta template_name);
\end{itemdecl}
\begin{itemdescr}
\pnum
\expects
\tcode{is_type(type) \&\& is_template(template_name)} is \tcode{true}.
\pnum
\returns
\tcode{true} if
\tcode{[:type:]} has an unambiguous and accessible base
that is a specialization of \tcode{[:template_name:]}, and
\tcode{false} otherwise.
\end{itemdescr}
\rSec1[qty.traits]{Traits}
\begin{itemdecl}
template<typename Rep>
constexpr bool @\libglobal{is_scalar}@ =
std::is_floating_point_v<Rep> || (std::is_integral_v<Rep> && !is_same_v<Rep, bool>);
template<typename Rep>
constexpr bool @\libglobal{is_vector}@ = false;
template<typename Rep>
constexpr bool @\libglobal{is_tensor}@ = false;
\end{itemdecl}
\begin{itemdescr}
\pnum
\remarks
Pursuant to \refcpp{namespace.std}\iref{spec.ext},
users may specialize \tcode{is_scalar}, \tcode{is_vector}, and \tcode{is_tensor} to \tcode{true}
for cv-unqualified program-defined types
which respectively represent
a scalar\irefiev{102-02-18},
a vector\irefiev{102-03-04}, and
% FIXME Undefined term.
a tensor,
and \tcode{false} for types which respectively do not.
\end{itemdescr}
\rSec1[qty.concepts]{Concepts}
\begin{itemdecl}
export template<typename T>
concept @\deflibconcept{representation}@ =
(is_scalar<T> || is_vector<T> || is_tensor<T>)&&std::regular<T> && @\exposidnc{scalable}@<T>;
\end{itemdecl}
\begin{itemdecl}
export template<typename T, quantity_character Ch>
concept @\deflibconcept{representation_of}@ =
@\libconcept{representation}@<T> && ((Ch == quantity_character::scalar && is_scalar<T>) ||
(Ch == quantity_character::vector && is_vector<T>) ||
(Ch == quantity_character::tensor && is_tensor<T>));
\end{itemdecl}
% FIXME Despite the `some_` prefix, it doesn't conform to the convention
% `template_of(^std::remove_cvref_t<T>) == ^template_name`.
\begin{itemdecl}
template<typename T>
concept @\defexposconceptnc{named-quantity-spec}@ =
(@\exposidnc{converts-to-base-subobject-of}@(^T, ^quantity_spec) && template_of(^T) != ^kind_of_);
template<typename T>
concept @\deflibconcept{some_quantity_spec}@ =
@\exposconceptnc{named-quantity-spec}@<T> ||
detail::IntermediateDerivedQuantitySpec<T> ||
template_of(^T) == ^kind_of;
\end{itemdecl}
\rSec1[qty.types]{Types}
\rSec2[qty.types.general]{General}
\pnum
A \defnadj{quantity}{type}
is a type \tcode{\placeholder{Q}}
that is a specialization of \tcode{quantity} or \tcode{quantity_point}.
\tcode{\placeholder{Q}} represents a quantity\irefiev{112-01-01}
with \tcode{\placeholder{Q}::rep} as its number
and \tcode{\placeholder{Q}::reference} as its reference.
\tcode{\placeholder{Q}} is a structural type\irefcppx{temp.param}{term.structural.type}
if \tcode{\placeholder{Q}::rep} is a structural type.
\pnum
Each class template defined in subclause \ref{qty.types}
has data members and special members specified below, and
has no base classes or members other than those specified.
\rSec2[qty.type]{Class template \tcode{quantity}}
\begin{codeblock}
namespace mp_units {
export template<@\libconcept{some_reference}@ auto R,
@\libconcept{representation_of}@<get_quantity_spec(R).character> Rep = double>
class quantity { @\unspec@ };
}
\end{codeblock}
Let \tcode{\placeholder{Q}} be a specialization of \tcode{quantity}.
\begin{itemize}
\item
If \tcode{Rep} is a scalar,
\tcode{\placeholder{Q}} represents a scalar quantity\irefiev{102-02-19}.
\item
If \tcode{Rep} is a vector,
\tcode{\placeholder{Q}} represents a vector\irefiev{102-03-04}.
% FIXME What if `Rep` is a tensor?
\end{itemize}
\rSec2[qty.point.type]{Class template \tcode{quantity_point}}
\begin{codeblock}
namespace mp_units {
export template<@\unspec@>
class quantity_point { @\unspec@ };
}
\end{codeblock}
A \defnadj{quantity point}{type} is a specialization of \tcode{quantity_point}.
Let \tcode{\placeholder{Q}} be a quantity point type.
\tcode{\placeholdernc{Q}::point_origin} represents
the origin point of a position vector\irefiev{102-03-15}.
\begin{itemize}
\item
If \tcode{Rep} is a scalar,
\tcode{\placeholder{Q}} represents the scalar quantity\irefiev{102-02-19}
of a position vector.
\item
If \tcode{Rep} is a vector,
\tcode{\placeholder{Q}} represents a position vector.
% FIXME What if `Rep` is a tensor?
\end{itemize}
\rSec1[qty.compat]{Compatibility}
\rSec1[qty.one]{Dimension one}
\rSec1[qty.systems]{Systems}
\rSec1[qty.chrono]{\tcode{std::chrono} compatibility}