From 8b7ff3532cd4de3232c044a9db9dd44bfd0f947e Mon Sep 17 00:00:00 2001 From: Xavier Leroy Date: Thu, 15 Oct 2020 15:07:31 +0200 Subject: [PATCH] Move the examples of labeled functions to StdLabels (#9976) In the old days, the interfaces of the labeled modules (ArrayLabels, BytesLabels, ListLabels, StringLabels) started with short examples of labelings. Now, the interfaces of the non-labeled modules (Array, Bytes, List, String) are automatically generated from the interfaces of the labeled modules. As a side effect, the interfaces of Array, Bytes, List and String also start with short examples of labelings, which is somewhat strange. This commit reorganizes the documentation as follows: - The documentation of the StdLabels module is expanded, and includes the examples of labeled functions previously scattered in ArrayLabels, BytesLabels, ListLabels, StringLabels. - Array, Bytes, List, String and their labeled counterparts briefly mention the labeled modules and point to StdLabels, but no longer contain examples. --- stdlib/array.mli | 13 +++---------- stdlib/arrayLabels.mli | 13 +++---------- stdlib/bytes.mli | 12 ++---------- stdlib/bytesLabels.mli | 12 ++---------- stdlib/list.mli | 12 ++---------- stdlib/listLabels.mli | 12 ++---------- stdlib/stdLabels.mli | 19 ++++++++++++++----- stdlib/string.mli | 14 +++----------- stdlib/stringLabels.mli | 14 +++----------- 9 files changed, 34 insertions(+), 87 deletions(-) diff --git a/stdlib/array.mli b/stdlib/array.mli index 3a828ac0b..489cb2346 100644 --- a/stdlib/array.mli +++ b/stdlib/array.mli @@ -23,16 +23,9 @@ (** Array operations. - The labeled version of this module, {!ArrayLabels}, is intended to be used - via {!StdLabels} which replaces {!Array}, {!Bytes}, {!List} and {!String} - with their labeled counterparts - - For example: - {[ - open StdLabels - - let everything = Array.create_matrix ~dimx:42 ~dimy:42 42 - ]} *) + The labeled version of this module can be used as described in the + {!StdLabels} module. +*) type 'a t = 'a array (** An alias for the type of arrays. *) diff --git a/stdlib/arrayLabels.mli b/stdlib/arrayLabels.mli index b30d0c05b..9ac8d9565 100644 --- a/stdlib/arrayLabels.mli +++ b/stdlib/arrayLabels.mli @@ -23,16 +23,9 @@ (** Array operations. - The labeled version of this module, {!ArrayLabels}, is intended to be used - via {!StdLabels} which replaces {!Array}, {!Bytes}, {!List} and {!String} - with their labeled counterparts - - For example: - {[ - open StdLabels - - let everything = Array.create_matrix ~dimx:42 ~dimy:42 42 - ]} *) + The labeled version of this module can be used as described in the + {!StdLabels} module. +*) type 'a t = 'a array (** An alias for the type of arrays. *) diff --git a/stdlib/bytes.mli b/stdlib/bytes.mli index 80bf91e47..ed149de32 100644 --- a/stdlib/bytes.mli +++ b/stdlib/bytes.mli @@ -47,16 +47,8 @@ Bytes are represented by the OCaml type [char]. - The labeled version of this module, {!BytesLabels}, is intended to be used - through {!StdLabels} which replaces {!Array}, {!Bytes}, {!List} and - {!String} with their labeled counterparts. - - For example: - {[ - open StdLabels - - let first = Bytes.sub ~pos:0 ~len:1 - ]} + The labeled version of this module can be used as described in the + {!StdLabels} module. @since 4.02.0 diff --git a/stdlib/bytesLabels.mli b/stdlib/bytesLabels.mli index e34f080e8..f38de076b 100644 --- a/stdlib/bytesLabels.mli +++ b/stdlib/bytesLabels.mli @@ -47,16 +47,8 @@ Bytes are represented by the OCaml type [char]. - The labeled version of this module, {!BytesLabels}, is intended to be used - through {!StdLabels} which replaces {!Array}, {!Bytes}, {!List} and - {!String} with their labeled counterparts. - - For example: - {[ - open StdLabels - - let first = Bytes.sub ~pos:0 ~len:1 - ]} + The labeled version of this module can be used as described in the + {!StdLabels} module. @since 4.02.0 diff --git a/stdlib/list.mli b/stdlib/list.mli index e6244f6a6..d86c609f9 100644 --- a/stdlib/list.mli +++ b/stdlib/list.mli @@ -33,16 +33,8 @@ The above considerations can usually be ignored if your lists are not longer than about 10000 elements. - The labeled version of this module, {!ListLabels}, is intended to be used - through {!StdLabels} which replaces {!Array}, {!Bytes}, {!List} and - {!String} with their labeled counterparts. - - For example: - {[ - open StdLabels - - let seq len = List.init ~f:(function i -> i) ~len - ]} + The labeled version of this module can be used as described in the + {!StdLabels} module. *) type 'a t = 'a list = [] | (::) of 'a * 'a list (**) diff --git a/stdlib/listLabels.mli b/stdlib/listLabels.mli index ef8478f99..ce5a7920e 100644 --- a/stdlib/listLabels.mli +++ b/stdlib/listLabels.mli @@ -33,16 +33,8 @@ The above considerations can usually be ignored if your lists are not longer than about 10000 elements. - The labeled version of this module, {!ListLabels}, is intended to be used - through {!StdLabels} which replaces {!Array}, {!Bytes}, {!List} and - {!String} with their labeled counterparts. - - For example: - {[ - open StdLabels - - let seq len = List.init ~f:(function i -> i) ~len - ]} + The labeled version of this module can be used as described in the + {!StdLabels} module. *) type 'a t = 'a list = [] | (::) of 'a * 'a list (**) diff --git a/stdlib/stdLabels.mli b/stdlib/stdLabels.mli index 4b24fd2b5..387b03f7d 100644 --- a/stdlib/stdLabels.mli +++ b/stdlib/stdLabels.mli @@ -15,12 +15,21 @@ (** Standard labeled libraries. - This meta-module provides labelized version of the {!Array}, - {!Bytes}, {!List} and {!String} modules. + This meta-module provides versions of the {!Array}, {!Bytes}, + {!List} and {!String} modules where function arguments are + systematically labeled. It is intended to be opened at the top of + source files, as shown below. - They only differ by their labels. Detailed interfaces can be found - in [arrayLabels.mli], [bytesLabels.mli], [listLabels.mli] - and [stringLabels.mli]. + {[ + open StdLabels + + let to_upper = String.map ~f:Char.uppercase_ascii + let seq len = List.init ~f:(function i -> i) ~len + let everything = Array.create_matrix ~dimx:42 ~dimy:42 42 + ]} + + Detailed interfaces documenting the function argument labels can be found + at {!ArrayLabels}, {!BytesLabels}, {!ListLabels} and {!StringLabels}. *) module Array = ArrayLabels diff --git a/stdlib/string.mli b/stdlib/string.mli index a3a87baf1..2f2d7f1b7 100644 --- a/stdlib/string.mli +++ b/stdlib/string.mli @@ -73,17 +73,9 @@ v} default until OCaml 4.05. Starting with 4.06, the compatibility mode is opt-in; we intend to remove the option in the future. - - The labeled version of this module, {!StringLabels}, is intended to be used - through {!StdLabels} which replaces {!Array}, {!Bytes}, {!List} and - {!String} with their labeled counterparts - - For example: - {[ - open StdLabels - - let to_upper = String.map ~f:Char.uppercase_ascii - ]} *) + The labeled version of this module can be used as described in the + {!StdLabels} module. +*) (** {1:strings Strings} *) diff --git a/stdlib/stringLabels.mli b/stdlib/stringLabels.mli index e4af5d4a5..3380f4228 100644 --- a/stdlib/stringLabels.mli +++ b/stdlib/stringLabels.mli @@ -73,17 +73,9 @@ v} default until OCaml 4.05. Starting with 4.06, the compatibility mode is opt-in; we intend to remove the option in the future. - - The labeled version of this module, {!StringLabels}, is intended to be used - through {!StdLabels} which replaces {!Array}, {!Bytes}, {!List} and - {!String} with their labeled counterparts - - For example: - {[ - open StdLabels - - let to_upper = String.map ~f:Char.uppercase_ascii - ]} *) + The labeled version of this module can be used as described in the + {!StdLabels} module. +*) (** {1:strings Strings} *)