From 39889e7f397cd132ac27ed36c50c02f879ddec0d Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 29 Nov 2021 18:14:37 +0100 Subject: [PATCH 1/7] doc: fix RST errors --- docs/alpha/consensus.rst | 2 +- docs/alpha/voting.rst | 4 ++-- docs/developer/javascript.rst | 17 ++++++++++------- docs/developer/michelson_instructions.rst | 10 +++++----- docs/developer/time_measurement_ppx.rst | 14 +++++--------- docs/protocols/tenderbake.rst | 4 ++-- 6 files changed, 25 insertions(+), 26 deletions(-) diff --git a/docs/alpha/consensus.rst b/docs/alpha/consensus.rst index 0b4090c9562f..0df7551dd354 100644 --- a/docs/alpha/consensus.rst +++ b/docs/alpha/consensus.rst @@ -150,7 +150,7 @@ balance). Let us first (re)define these and related concepts. of the maximum active stake during the last ``PRESERVED_CYCLES + MAX_SLASHING_PERIOD``. This amount represents the delegate's skin in the game: in the case that the delegate behaves badly, its frozen deposit is partly slashed (see - :ref:`slashing`). Taking the maximum over an + :ref:`slashing_alpha`). Taking the maximum over an interval of cycles (instead of just considering the active stake at the cycle where the bad action can occur) allows to avoid situations where a malicious delegate empties its accounts between the time when diff --git a/docs/alpha/voting.rst b/docs/alpha/voting.rst index ee5b5044f58d..52eed5944d66 100644 --- a/docs/alpha/voting.rst +++ b/docs/alpha/voting.rst @@ -318,8 +318,8 @@ Further External Resources Further details and explanations on the voting procedure can be found at: -- `the Open Tezos entry`_ -- `the Tezos Agora entry`_. +- `Governance on-chain `_ on Open Tezos +- `Tezos Governance `_ on Tezos Agora. For more details on the client commands refer to the manual at :ref:`client_manual_alpha`. diff --git a/docs/developer/javascript.rst b/docs/developer/javascript.rst index 72c3ae59695a..8689523384f2 100644 --- a/docs/developer/javascript.rst +++ b/docs/developer/javascript.rst @@ -1,5 +1,5 @@ Compiling (part of) the Octez codebase to JavaScript -================================================== +==================================================== We want to expose a JavaScript API while staying in sync with the OCaml codebase. A way to achieve this is to compile OCaml code to @@ -29,6 +29,7 @@ One way to achieve this is to rely on ``nvm``. Use the following commands to install `nvm` and `node`: :: + curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash scripts/install_builld_deps.js.sh @@ -69,8 +70,8 @@ alcotest tests in JavaScript: - and a new rule in the dune file to execute the test with node. - dune build @runtest_js - :: + (tests (names mytest) (libraries alcotest) @@ -91,11 +92,12 @@ In order to run inline_tests in javascript: - run `dune exec ./src/tooling/run_js_inline_tests.exe` :: - (library - (name mylib) - (js_of_ocaml) - (inline_tests) - ) + + (library + (name mylib) + (js_of_ocaml) + (inline_tests) + ) JavaScript test failures ------------------------ @@ -104,6 +106,7 @@ There are plenty of reasons that can explain why a test fails when running in JavaScript and succeed otherwise. Here is a non exhaustive list: + - Integer (``int``) are 32bit, not 63bit. - The stack is much smaller by default on JavaScript VMs, it's easier to stackoverflow. - There is no general tailcall optimization. In particular, cps will not be optimized. diff --git a/docs/developer/michelson_instructions.rst b/docs/developer/michelson_instructions.rst index 530ffa61cdfb..47cb26f81ac1 100644 --- a/docs/developer/michelson_instructions.rst +++ b/docs/developer/michelson_instructions.rst @@ -91,7 +91,7 @@ Michelson types Before we talk about internal representations, we need to have a brief look at how the interpreter handles types of Michelson expressions internally. Types ``ty`` and ``stack_ty`` are both defined in -:src:`/src/proto_alpha/lib_protocol/script_typed_ir.ml`. Type ``ty`` enumerates +:src:`src/proto_alpha/lib_protocol/script_typed_ir.ml`. Type ``ty`` enumerates all types known to the Michelson interpreter and is parametrised by the underlying OCaml type in which Michelson values are actually stored in memory. Thus, when values of the ty type are pattern-matched on, their type parameters @@ -148,7 +148,7 @@ For instance ``ICar`` instruction is defined as:: The reason why the third parameter of the resulting ``kinstr`` is ``'r`` and not simply ``'a`` (which is the type of the first element of the pair at the top of the -initial stack) is because this constructor also contains the next instruction, +initial stack) is because this constructor also contains the next instruction, which produces a value of some arbitrary type ``'r``. However, note that this next instruction should expect ``'a`` at the top of its initial stack. @@ -184,7 +184,7 @@ The translator Now that we have chosen a primitive to represent our instruction in the code and an internal representation (IR), we need to provide a rule that translates the former into the latter. ``parse_instr`` function in -:src:`/src/proto_alpha/lib_protocol/script_ir_translator.ml` is responsible for +:src:`src/proto_alpha/lib_protocol/script_ir_translator.ml` is responsible for this. Notice that the function ``parse_instr``, despite what its name suggests, matches on pre-parsed Micheline AST. Micheline parser is not a part of the protocol and therefore must be run by the client before the script is submitted @@ -215,7 +215,7 @@ correct), which makes for faster execution. For this reason it is essential that each IR contains a value of type ``kinfo`` (or an equivalent thereof), from which the translator can obtain the type the stack should have after this instruction is executed. Function ``kinfo_of_kinstr`` in -:src:`/src/proto_alpha/lib_protocol/script_typed_ir.ml` is responsible for this +:src:`src/proto_alpha/lib_protocol/script_typed_ir.ml` is responsible for this extraction. An interesting situation occurs with instructions regulating control flow. These @@ -242,7 +242,7 @@ The precise return type of ``parse_instr`` is ``judgement`` defined in apply : 'r 'f. ('a, 's) kinfo -> ('b, 'u, 'r, 'f) kinstr -> ('a, 's, 'r, 'f) kinstr; } - + type ('a, 's, 'b, 'u) descr = { loc : Script.location; bef : ('a, 's) stack_ty; diff --git a/docs/developer/time_measurement_ppx.rst b/docs/developer/time_measurement_ppx.rst index f8d409b47333..d77da1255172 100644 --- a/docs/developer/time_measurement_ppx.rst +++ b/docs/developer/time_measurement_ppx.rst @@ -12,7 +12,7 @@ expressions and to log these measurements when desired. Since it uses together with ``Tezt`` framework to perform the benchmarking of specific parts of Tezos node. -**This PPX is only intended to be used for tests. As the current runtime +**This PPX is only intended to be used for tests. As the current runtime implemetation performs memory allocation, an unwise usage could mess with the garbage collector or blow up your memory.** @@ -95,7 +95,7 @@ time measurement in order to discriminate it later. This key is computed from th that was given inside the attribute ``[@time.duration f_time]``. ``"f_time"`` is the label of the key, an identifier that represents the name of the measurement. -``[]`` is a list of string that contains some additional metadata. It can be useful +``[]`` is a list of strings that contains some additional metadata. It can be useful to distinguish several measurements registered with the same label, for example if the expression is evaluated in a loop. In our case, the list is empty because no metadata was provided in the attribute's payload. @@ -145,7 +145,7 @@ is displayed on standard output. For example: .. code-block:: - Aug 23 17:52:58.593 - benchmarking: time measurements: + Aug 23 17:52:58.593 - benchmarking: time measurements: Aug 23 17:52:58.593 - benchmarking: [(f_time, 0.000177); (g_time, 0.005658)] Compatible Ocaml Attributes @@ -157,13 +157,13 @@ The PPX provides the handling of three attributes: Ocaml expressions execution. The ``