diff --git a/doc/code-issues.rst b/doc/code-issues.rst index 0b376e78..db5d8be3 100644 --- a/doc/code-issues.rst +++ b/doc/code-issues.rst @@ -15,7 +15,7 @@ Some code conventions are checked by the ``make codepolicycheck`` target. Basic conventions ================= -Indentantion, naming, etc +Indentation, naming, etc. ------------------------- Indent with tab. On continuation lines indent with tab to shared indent @@ -33,7 +33,7 @@ Names are lowercase, underscore separated:: /* ... */ } -Local functions, arrays, structs, typedefs, etc have a double underscore +Local functions, arrays, structs, typedefs, etc. have a double underscore after "duk":: typedef int duk__temptype; @@ -60,7 +60,7 @@ interest only can have a local name or have a double underscore after "DUK":: /* select DUK_FOO provider */ #define DUK_FOO DUK_FOO_ALT2 -There is only one space after a ``#define``, ``#if``, etc, but there may be +There is only one space after a ``#define``, ``#if``, etc., but there may be multiple spaces between the a macro name and its definition. There is no strict rule on the alignment of a macro value; successive definitions usually keep values in the same column. @@ -171,7 +171,7 @@ Comment styles -------------- A block or "banner" comment is used in file headers and to distinguish logical -sections containing (typically) multiple functions, definitions, variables, etc:: +sections containing (typically) multiple functions, definitions, variables, etc.:: /* * First line is empty and there are two spaces between the star @@ -220,7 +220,7 @@ ending period (i.e. the text is not a sentence):: } A comment on the same line as a statement is separate by two spaces. Don't -use C++ style comments as they're not portable:: +use C++ style comments, as they're not portable:: static void duk__helper(char *values, int count) { int i; /* loop counter */ @@ -765,7 +765,7 @@ There are several issues related to symbol visibility: * Minimality: Duktape should only expose the function and data symbols that are used by calling programs. This is a hygiene issue but also affects compiler optimization: if a function is internal, it doesn't need to conform - to a rigid ABI which allows some optimizations. See e.g. + to a rigid ABI, which allows some optimizations. See e.g. https://gcc.gnu.org/wiki/Visibility. * Single file vs. separate files: symbols need to be declared differently @@ -872,7 +872,7 @@ MSVC DLL import/export ---------------------- For MSVC, DLL import/export attributes are needed to build as a DLL. -When compiling Duktape public symbols should be declared as "dllexport" +When compiling Duktape, public symbols should be declared as "dllexport" in both header files and the actual declarations. When compiling a user application, the same header symbols must be declared as "dllimport". The compilation context is available through ``DUK_COMPILING_DUKTAPE``. diff --git a/doc/fastint.rst b/doc/fastint.rst index 67fcbfbb..c357c27f 100644 --- a/doc/fastint.rst +++ b/doc/fastint.rst @@ -111,7 +111,7 @@ tips for using fastints: // All 'i' values here will be fastints. } -* Note that the number syntax doesn't affect the fastint downgrade check, +* Note that the number syntax doesn't affect the fastint downgrade check; only the final value matters. All of the following will be represented as fastints:: @@ -120,7 +120,7 @@ tips for using fastints: t = 100e-2; t = 0.01e2; - Similarly constant folding, when possible, will be done before doing the + Similarly, constant folding, when possible, will be done before doing the downgrade check, so the following will be represented as a fastint:: t = 123.123 / 123.123; // fastint 1 @@ -206,7 +206,7 @@ Fastints and Duktape internals A few notes on how fastints are used internally, what macros are used, etc. -Fastint aware vs. unware code +Fastint aware vs. unaware code ----------------------------- Fastint support is optional and added between ``#if defined()`` guards:: @@ -219,7 +219,7 @@ Number handling will be either: * fastint unaware: requires no changes to existing code -* fastint aware: requires fastint detection e.g. in switch-case statements +* fastint aware: requires fastint detection, e.g. in switch-case statements and then usage of fastint aware macros Type switch cases @@ -366,7 +366,7 @@ downgrade check:: DUK_TVAL_CHKFAST_INPLACE(tv); -The target 'tv' can have any type; the macro first checks if the value +The target ``tv`` can have any type; the macro first checks if the value is a double and if so, if it can be fastint coerced. When fastint support is disabled, the macro is a no-op. @@ -614,7 +614,7 @@ if a double value can be represented as a fastint. The "fast path" for fastint operations doesn't execute this algorithm because both inputs and outputs are fastints and Duktape detects this in the fast path -preconditions. Even so the performance of the downgrade check matters for +preconditions. Even so, the performance of the downgrade check matters for overall performance. Exponent and sign by cases @@ -943,7 +943,7 @@ arithmetic would certainly be faster. The downside would be that some bit operations won't be possible: to fully support all bit operations both signed and unsigned 32-bit values -is needed. +are needed. Optimize upgrade and downgrade ------------------------------ diff --git a/doc/git-conventions.rst b/doc/git-conventions.rst index 826f2bae..aac3031e 100644 --- a/doc/git-conventions.rst +++ b/doc/git-conventions.rst @@ -10,8 +10,8 @@ The main development repository is hosted on GitHub: * https://github.com/svaarala/duktape The duktape.org website is also part of the repository. Up to Duktape 0.12.0 -also the release binaries were stored in the Duktape repo. For Duktape 1.0.0 -and after the convention is changed to use external binaries, see releases +the release binaries were also stored in the Duktape repo. For Duktape 1.0.0 +and after the convention is changed to use external binaries; see the Releases section below. The upside of keeping the website in the same repo is that old documentation matching the current checkout is always available. @@ -30,7 +30,7 @@ Issues are tracked in GitHub, i.e. outside the repository itself. Releases ======== -Release versioning follows semantic versioning, for details, see: +Release versioning follows semantic versioning; for details, see: * http://duktape.org/guide.html#versioning @@ -66,12 +66,12 @@ Branch and tag naming Development branches: * ``master``: Churn branch with active development, kept close to release - quality at all times, unstable features are developed in feature branches. + quality at all times; unstable features are developed in feature branches. -* ``frob-xyz-tweaks``, ``add-missing-docs``, etc: Relatively short lived - branches for developing a particular feature, may be rebased, commits may +* ``frob-xyz-tweaks``, ``add-missing-docs``, etc.: Relatively short lived + branches for developing a particular feature; may be rebased, commits may be squashed, etc. Merged into ``master`` when code works, documentation - has been updated, etc and then deleted. There is no fixed branch naming + has been updated, etc., and then deleted. There is no fixed branch naming but avoid ``fix-`` and ``bug-`` prefixes. * ``fix-xxx``: Short lived bug fix branch, otherwise similar to a feature @@ -153,7 +153,7 @@ Commit messages Merges to master branch must have clean commit messages. Merge commit should retain the default merge heading which should be followed by a descriptive paragraph similar to what the release note updates are. -This makes the merge commits useful for getting an overview what changes +This makes the merge commits useful for getting an overview of what changes have been made and why. Commit messages should follow these guidelines: @@ -161,7 +161,7 @@ Commit messages should follow these guidelines: * Capitalized title line at most 50 characters long, no trailing period. This works best with GitHub and is also a common convention. -* Beneath that use normal sentence structure, bullet lists etc are OK. +* Beneath that use normal sentence structure, bullet lists etc. are OK. No particular format for this part now. * GitHub compatible messages are nice: diff --git a/doc/logging.rst b/doc/logging.rst index 5ebdd598..d26e5c8d 100644 --- a/doc/logging.rst +++ b/doc/logging.rst @@ -19,7 +19,7 @@ provides the same bindings (``Duktape.Logger`` object, ``duk_log()`` and The framework focuses on how logger objects are created and what the logger interface looks like. Other features are quite barebones; for -example the default backend simply writes to the ``stderr`` and there is +example, the default backend simply writes to the ``stderr`` and there is no advanced backend configuration like multiple log outputs. The user can easily replace the frontend and the backend functions to extend the basic feature set in a transparent manner. @@ -239,7 +239,7 @@ intentional to keep the logger footprint small: writes go through a single logger instance. If multiple global objects exist in the Duktape heap, each global context (or more specifically ``Duktape.Logger`` instance) will have its own logger object. Logging - from C is usually less of a priority so the logging C api is kept very + from C is usually less of a priority so the logging C API is kept very minimal on purpose. Existing frameworks and related links diff --git a/doc/release-checklist.rst b/doc/release-checklist.rst index 0d53394c..b18b61c1 100644 --- a/doc/release-checklist.rst +++ b/doc/release-checklist.rst @@ -342,7 +342,7 @@ Checklist for maintenance releases * Review diff between previous release and new patch release. -* Tag release, description "maintenance release" should be good enough for +* Tag release; description "maintenance release" should be good enough for most patch releases. * Build release. Compare release to previous release package by diffing the diff --git a/doc/rst-conventions.rst b/doc/rst-conventions.rst index 0f2ae2af..7d1ef11e 100644 --- a/doc/rst-conventions.rst +++ b/doc/rst-conventions.rst @@ -16,7 +16,7 @@ Book level: #. Over- and underlined hash marks (``#``) for book title -#. Over- and underlines stars (``*``) for book sub-title +#. Over- and underlined stars (``*``) for book sub-title File level: @@ -63,8 +63,8 @@ However, e.g. GitHub will renumber the bullets and may also change the numbering style. This will make references to list elements confusing; e.g. if you refer to Quux as element 1.a.1 above, the reference is quite confusing if Quux was renumbered to 1.1.1 or 1.a.iii. Even so, such -references are sometimes necessary so they can be used. -Start at zero indent +references are sometimes necessary, so they can be used. +Start at zero indent. Bullets ------- diff --git a/doc/system-install.rst b/doc/system-install.rst index 17942b85..8f2cdc38 100644 --- a/doc/system-install.rst +++ b/doc/system-install.rst @@ -45,7 +45,7 @@ There a few limitations in this approach: Duktape because there are a lot of config options. * Technically the Duktape library and the user application should be compiled - with the same compiler. When using different compilers basic types or + with the same compiler. When using different compilers, basic types or struct alignment rules (among other things) may differ. In practice it's unlikely you'll run into problems, at least when using mainline compilers like gcc and clang. diff --git a/doc/unicode-support.rst b/doc/unicode-support.rst index 02def10a..66a0ae16 100644 --- a/doc/unicode-support.rst +++ b/doc/unicode-support.rst @@ -25,7 +25,7 @@ The general principles for implementation are: * Compile-time operations on non-ASCII characters can have a performance penalty in exchange for small size. -Handling unicode case conversion, character classes etc in a compact code +Handling Unicode case conversion, character classes, etc. in a compact code size is bit challenging. The current solution is to fast path ASCII characters and to use a bit-packed format for encoding case conversion rules (e.g. range mappings). The rules are created by build-time Python