diff options
Diffstat (limited to 'doc/references')
| -rw-r--r-- | doc/references/CodingStyle.rst | 170 | ||||
| -rw-r--r-- | doc/references/CommandReference.rst | 28 |
2 files changed, 123 insertions, 75 deletions
diff --git a/doc/references/CodingStyle.rst b/doc/references/CodingStyle.rst index 76d33b5ca..ddecb6339 100644 --- a/doc/references/CodingStyle.rst +++ b/doc/references/CodingStyle.rst @@ -1,7 +1,7 @@ .. _REF:Style: -Coding style -################# +Coding Style +############ Ada subset: use only a simple (VHDL like) subset of Ada: no tasking, no controlled types... VHDL users should easily understand that subset. @@ -15,77 +15,125 @@ But: 3 spaces for indentation. No trailing spaces, not TAB (HT). Subprograms must have a comment before to describe it, like: + +.. code-block:: Ada + -- Analyze the concurrent statements of PARENT. procedure Sem_Concurrent_Statement_Chain (Parent : Iir); + The line before the comment must be a blank line (unless this is the first declaration). Don't repeat the comment before the subprogram body. * For subprograms: -1) Declare on one line when possible: - function Translate_Static_Aggregate (Aggr : Iir) return O_Cnode - -2) If not possible, put the return on the next line: - function Translate_Static_String (Str_Type : Iir; Str_Ident : Name_Id) - return O_Cnode - -3) If not possible, put parameters and return on the next line: - function Create_String_Literal_Var_Inner - (Str : Iir; Element_Type : Iir; Str_Type : O_Tnode) return Var_Type - -4) If not possible, return on the next line: - function Translate_Shortcut_Operator - (Imp : Iir_Implicit_Function_Declaration; Left, Right : Iir) - return O_Enode - -5) If not possible, one parameter per line, just after subprogram name: - procedure Translate_Static_Aggregate_1 (List : in out O_Array_Aggr_List; - Aggr : Iir; - Info : Iir; - El_Type : Iir) -6) If not possible, add a return after subprogram name: - function Translate_Predefined_TF_Array_Element - (Op : Predefined_Boolean_Logical; - Left, Right : Iir; - Res_Type : Iir; - Loc : Iir) - return O_Enode - -7) If not possible, ask yourself what is wrong! Shorten a name. + + 1. Declare on one line when possible: + + .. code-block:: Ada + + function Translate_Static_Aggregate (Aggr : Iir) return O_Cnode + + 2. If not possible, put the return on the next line: + + .. code-block:: Ada + + function Translate_Static_String (Str_Type : Iir; Str_Ident : Name_Id) + return O_Cnode + + 3. If not possible, put parameters and return on the next line: + + .. code-block:: Ada + + function Create_String_Literal_Var_Inner + (Str : Iir; Element_Type : Iir; Str_Type : O_Tnode) return Var_Type + + 4. If not possible, return on the next line: + + .. code-block:: Ada + + function Translate_Shortcut_Operator + (Imp : Iir_Implicit_Function_Declaration; Left, Right : Iir) + return O_Enode + + 5. If not possible, one parameter per line, just after subprogram name: + + .. code-block:: Ada + + procedure Translate_Static_Aggregate_1 (List : in out O_Array_Aggr_List; + Aggr : Iir; + Info : Iir; + El_Type : Iir) + + 6. If not possible, add a return after subprogram name: + + .. code-block:: Ada + + function Translate_Predefined_TF_Array_Element + (Op : Predefined_Boolean_Logical; + Left, Right : Iir; + Res_Type : Iir; + Loc : Iir) + return O_Enode + + 7) If not possible, ask yourself what is wrong! Shorten a name. * Rule for the 'is': one a new line only if the declarative part is not empty: - procedure Translate_Assign (Target : Mnode; Expr : Iir; Target_Type : Iir) - is - Val : O_Enode; - begin -vs - function Translate_Static_Range_Dir (Expr : Iir) return O_Cnode is - begin - -If the parametere line is too long with the 'is', put in on a separate line: - procedure Predeclare_Scope_Type - (Scope : in out Var_Scope_Type; Name : O_Ident) is + + .. code-block:: Ada + + procedure Translate_Assign (Target : Mnode; Expr : Iir; Target_Type : Iir) + is + Val : O_Enode; + begin + + vs. + + .. code-block:: Ada + + function Translate_Static_Range_Dir (Expr : Iir) return O_Cnode is + begin + + If the parametere line is too long with the 'is', put in on a separate line: + + .. code-block:: Ada + + procedure Predeclare_Scope_Type + (Scope : in out Var_Scope_Type; Name : O_Ident) is * Generic instantiation: put the generic actual part on a new line: - procedure Free is new Ada.Unchecked_Deallocation - (Action_List, Action_List_Acc); + + .. code-block:: Ada + + procedure Free is new Ada.Unchecked_Deallocation + (Action_List, Action_List_Acc); * For if/then statement: -1) 'then' on the same line: - if Get_Expr_Staticness (Decl) = Locally then - -2) If not possible, 'then' is alone on its line aligned with the 'if': - if Expr = Null_Iir - or else Get_Kind (Expr) = Iir_Kind_Overflow_Literal - then -3) For a multiline condition, 'or else' and 'and then' should start lines. + 1. 'then' on the same line: + + .. code-block:: Ada + + if Get_Expr_Staticness (Decl) = Locally then + + 2. If not possible, 'then' is alone on its line aligned with the 'if': + + .. code-block:: Ada + + if Expr = Null_Iir + or else Get_Kind (Expr) = Iir_Kind_Overflow_Literal + then + + 3. For a multiline condition, 'or else' and 'and then' should start lines. * 'Local' variable declaration: -Do not initialize variables, constants must be declared before variables: - is - N_Info : constant Iir := Get_Sub_Aggregate_Info (Info); - Assoc : Iir; - Sub : Iir; - begin -If the initialization expression has a side effect (such as allocation), do -not use a constant.
\ No newline at end of file + Do not initialize variables, constants must be declared before variables: + + .. code-block:: Ada + + is + N_Info : constant Iir := Get_Sub_Aggregate_Info (Info); + Assoc : Iir; + Sub : Iir; + begin + + If the initialization expression has a side effect (such as allocation), do + not use a constant.
\ No newline at end of file diff --git a/doc/references/CommandReference.rst b/doc/references/CommandReference.rst index 4adb2dd36..2d7dc491a 100644 --- a/doc/references/CommandReference.rst +++ b/doc/references/CommandReference.rst @@ -7,7 +7,7 @@ Command Reference .. HINT:: The most common commands and options are shown in section :ref:`USING:Invoking`. Here the advanced and experimental features are described. Environment variables -============= +===================== .. envvar:: GHDL_PREFIX @@ -21,7 +21,7 @@ There are a few GHDL commands which are seldom useful. .. index:: cmd help Help [:samp:`-h`] ------------- +----------------- .. option:: --help, -h @@ -36,7 +36,7 @@ for this later command are displayed:: .. index:: cmd display configuration Display config [:samp:`--disp-config`] -------------------- +-------------------------------------- .. option:: --disp-config <[options]> @@ -46,7 +46,7 @@ Display the program paths and options used by GHDL. This may be useful to track .. index:: display :samp:`std.standard` Display standard [:samp:`--disp-standard`] ---------------------- +------------------------------------------ .. option:: --disp-standard <[options]> @@ -55,7 +55,7 @@ Display the :samp:`std.standard` package. .. index:: cmd version Version [:samp:`--version`] ---------------- +--------------------------- .. option:: --version, -v @@ -70,7 +70,7 @@ The following commands act on one or several files. These are not analyzed, ther .. index:: vhdl to html Pretty print [:samp:`--pp-html`] --------------------- +-------------------------------- .. option:: --pp-html <[options] file...> @@ -84,7 +84,7 @@ The style of the html file can be modified with the :option:`--format=` option: .. index:: cmd file find Find [:samp:`-f`] ------------- +----------------- .. option:: -f <file...> @@ -93,7 +93,7 @@ The files are scanned, parsed and the names of design units are displayed. Desig .. index:: cmd file chop Chop [:samp:`--chop`] ------------- +--------------------- .. option:: --chop <files...> @@ -112,19 +112,19 @@ This command may be useful to split big files, if your computer has not enough m .. index:: cmd file lines Lines [:samp:`--lines`] -------------- +----------------------- .. option:: --lines <files...> Display on the standard output lines of files preceded by line number. GCC/LLVM only commands -================= +====================== .. index:: cmd GCC/LLVM binding Bind [:samp:`--bind`] ------------- +--------------------- .. option:: --bind <[options] primary_unit [secondary_unit]> @@ -133,7 +133,7 @@ Performs only the first stage of the elaboration command; the list of objects fi .. index:: cmd GCC/LLVM linking Link [:samp:`--link`] ------------- +--------------------- .. option:: --link <[options] primary_unit [secondary_unit]> @@ -142,14 +142,14 @@ Performs only the second stage of the elaboration command: the executable is cre .. index:: cmd GCC/LLVM list link List link [:samp:`--list-link`] ------------------ +------------------------------- .. option:: --list-link <primary_unit [secondary_unit]> This command may be used only after a bind command. GHDL displays all the files which will be linked to create an executable. This command is intended to add object files in a link of a foreign program. Options -================= +======= .. option:: --mb-comments, -C |