Permalink
Browse files

[doc] review: Review of stdlib.core

  • Loading branch information...
1 parent 4f89539 commit 62c92c3205d091d0c8114297193eafea66537d98 Guillem Rieu committed Jun 17, 2011
View
@@ -18,13 +18,32 @@
/**
- * Binary data handling: for any sequence of bytes that is not to be considered as text
+ * Binary data handling: for any sequence of bytes that is not to be considered
+ * as text.
+ *
* @destination PRIVATE
* @stability UNSTABLE
*/
+/**
+ * {1 About this module}
+ *
+ * {1 Where should I start?}
+ *
+ * {1 What if I need more?}
+ */
+
+/**
+ * {1 Types defined in this module}
+ */
+
//TODO:This should be [external]. However, for the moment, we rely on [static_file_include] and we just can't.
@opacapi
type binary = string
+
+/**
+ * {1 Interface}
+ */
+
string_of_binary(x:binary) = @unsafe_cast(x): string
binary_of_string(x:string) = @unsafe_cast(x): binary
View
@@ -15,6 +15,7 @@
You should have received a copy of the GNU Affero General Public License
along with OPA. If not, see <http://www.gnu.org/licenses/>.
*/
+
/**
* Basic functions on booleans.
*
@@ -25,10 +26,26 @@
*/
/**
+ * {1 About this module}
+ *
+ * {1 Where should I start?}
+ *
+ * {1 What if I need more?}
+ */
+
+/**
+ * {1 Types defined in this module}
+ */
+
+/**
* Order type label for bool
*/
type Bool.order = Order.default
+/**
+ * {1 Interface}
+ */
+
Bool =
{{
/**
View
@@ -23,11 +23,24 @@
| CactUTF interface |
-------------------*/
-/*
-** The purpose of this file is to permit the use of the functions of
-** cactutf.ml into the module Text in opa.
-** For a description of the functions, see cactutf.ml
-*/
+/**
+ * The purpose of this file is to permit the use of the functions of
+ * cactutf.ml into the module Text in opa.
+ *
+ * For a description of the functions, see cactutf.ml
+ */
+
+/**
+ * {1 About this module}
+ *
+ * {1 Where should I start ?}
+ *
+ * {1 What if I need more?}
+ */
+
+/**
+ * {1 Interface}
+ */
Cactutf = {{
View
@@ -19,18 +19,28 @@
@abstract type Char.order = void
/**
- * {1 About this module}
- *
- * Here are provided some basic functionality on characters
- * Characters only represent the ASCII set
- *
* @category data
* @destination public
* @author Valentin Gatien-Baron, 2010 (documentation)
* @author Sarah Maarek, 2010 (review)
* @stability stable
+ */
+
+/**
+ * {1 About this module}
+ *
+ * Here are provided some basic functionality on characters
+ * Characters only represent the ASCII set
+ *
+ * {1 Where should I start ?}
+ *
+ * {1 What if I need more?}
**/
+/**
+ * {1 Interface}
+ */
+
Char = {{
/**
@@ -15,14 +15,21 @@
You should have received a copy of the GNU Affero General Public License
along with OPA. If not, see <http://www.gnu.org/licenses/>.
*/
+
/**
- * {1 About this module}
- *
* @category compiler interface
* @destination internal use, private
- * @author Valentin Gatien-Baron, 2011 (adhoc serialization)
+ * @author Valentin Gatien-Baron, 2011 (ad hoc serialization)
* @author Mathieu Barbin, 2011 (review)
* @stability stable
+ */
+
+/**
+ * {1 About this module}
+ *
+ * {1 Where should I start ?}
+ *
+ * {1 What if I need more?}
**/
/**
@@ -32,6 +39,10 @@
**/
/**
+ * {3 Types}
+ */
+
+/**
* BEWARE: the compiler generate this type in qmljs_Serializer
* @opacapi
**/
@@ -46,6 +57,10 @@ type Client_code.output =
{adhoc : string; package_ : string}
/ {ast : JsAst.code}
+/**
+ * {3 Interface}
+ */
+
Core_client_code =
{{
/*
@@ -87,12 +102,20 @@ Core_client_code =
**/
/**
+ * {3 Types}
+ */
+
+/**
* BEWARE: the compiler generates this type in pass_GenerateServerAst
* @opacapi
**/
type ServerCode.t =
{adhoc : string; package_ : string}
+/**
+ * {3 Interface}
+ */
+
Core_server_code =
{{
@private server_codes = ServerReference.create([]:list(ServerCode.t))
View
@@ -15,6 +15,7 @@
You should have received a copy of the GNU Affero General Public License
along with OPA. If not, see <http://www.gnu.org/licenses/>.
*/
+
/**
* Defining API on external continuation.
*
@@ -36,6 +37,10 @@
*
* Since the continuation will also be the native support of transactions,
* there is a need for an API.
+ *
+ * {1 Where should I start?}
+ *
+ * {1 What if I need more?}
**/
/**
@@ -50,6 +55,10 @@ type bycps__unit = external
@opacapi
type continuation('a) = external
+/**
+ * {1 Interface}
+ */
+
Continuation = {{
/**
@@ -103,7 +112,7 @@ Continuation = {{
* The type of a future.
* Currently, used by generated code only.
* May become used by the user, if we export the
- * concurrency primitives spaw, wait.
+ * concurrency primitives spawn, wait.
**/
@opacapi
type Cps.future('a) = external
View
@@ -15,6 +15,7 @@
You should have received a copy of the GNU Affero General Public License
along with OPA. If not, see <http://www.gnu.org/licenses/>.
*/
+
/**
* Debugging utilities
*
@@ -23,6 +24,18 @@
* @stability stabilizing
*/
+/**
+ * {1 About this module}
+ *
+ * {1 Where should I start?}
+ *
+ * {1 What if I need more?}
+ */
+
+/**
+ * {1 Interface}
+ */
+
Debug = {{
@deprecated({use="the directive @fail"})
View
@@ -15,17 +15,23 @@
You should have received a copy of the GNU Affero General Public License
along with OPA. If not, see <http://www.gnu.org/licenses/>.
*/
+
/**
- * Arguments for taging part of the code as deprecated.
+ * Arguments for tagging part of the code as deprecated.
**/
/**
+ * {1 About this module}
+ *
* This module defines the type of the argument of the directive @deprecated
+ *
* These arguments are read at compile time, and should use literal only.
* @see pass_CodingDirectives
* @see opa parser
*
- * here are some example of use:
+ * {1 Where should I start?}
+ *
+ * Here are some example of use:
*
* {[
* @deprecated({use="bar"}) foo = bar
@@ -35,7 +41,12 @@
* @deprecated({hint="Please refactor your code, this function does no longer exists"}) foo = ...
* }
*
-**/
+ * {1 What if I need more?}
+ */
+
+/**
+ * {1 Types defined in this module}
+ */
/**
* Argument of the @deprecated directive
@@ -48,7 +59,7 @@ type Deprecated.argument =
* @deprecated({use="this_function"}) deprec_fun() = void
* do deprec_fun()
* }
- * will produce a warning around the utilisation of the deprec_fun, telling :
+ * will produce a warning around the utilization of the deprec_fun, telling :
* {This code uses a deprecated construction. Please use "this_function" instead}
**/
{ use : string }
@@ -15,6 +15,7 @@
You should have received a copy of the GNU Affero General Public License
along with OPA. If not, see <http://www.gnu.org/licenses/>.
*/
+
/**
* Common Opa Exceptions
*
@@ -50,6 +51,10 @@
* catch
* | { e } ->
* }
+ *
+ * {1 Where should I start?}
+ *
+ * {1 What if I need more?}
**/
type Exception.common =
@@ -16,13 +16,29 @@
along with OPA. If not, see <http://www.gnu.org/licenses/>.
*/
+/**
+ * {1 About this module}
+ *
+ * {1 Where should I start?}
+ *
+ * {1 What if I need more?}
+ */
+
+/**
+ * {1 Types defined in this module}
+ */
+
@opacapi
type finite_single_thread_lazy('a) = Mutable.t(
{ delayed : -> 'a } /* a lazy not yet evaluated */
/ { evaluating } /* a value that is being forced right now */
/ { value : 'a } /* a lazy that has been computed before */
)
+/**
+ * {1 Interface}
+ */
+
/** Use by the compiler to implement non lambda recursive values, where recursions are lambda guarded (hence evaluating the recursion has a chance to be finite).
Do not use it for any other purpose then finite lazy values with non concurrent force calls */
FiniteSingleThreadLazy = {{
View
@@ -73,7 +73,7 @@ void={}:void
/**
* {1 Comparison functions}
*
- * All comparision functions return a boolean.
+ * All comparison functions return a boolean.
*/
@@ -106,7 +106,7 @@ compare(a,b) = OpaValue.compare(a,b)
`==`(a:'a,b:'a):bool = match compare(a,b) with {eq} -> true | _ -> false
/**
- * Universal comparaison functions
+ * Universal comparison functions
*/
@specialize(String.`lt`,Int.`<`,Float.`<`,Char.`lt`)
@@ -426,7 +426,7 @@ unfold = for
else
/*
JS imp backend may simplify pattern matching generated
- from && in opa code. We can easyer match the form of
+ from && in opa code. We can easily match the form of
the generated code if the following bool is syntactic.
Do not replace it with the identifier [false]
*/
Oops, something went wrong.

0 comments on commit 62c92c3

Please sign in to comment.