Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/leptonica/style-guide.txt @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 /*====================================================================*
2 - Copyright (C) 2001 Leptonica. All rights reserved.
3 -
4 - Redistribution and use in source and binary forms, with or without
5 - modification, are permitted provided that the following conditions
6 - are met:
7 - 1. Redistributions of source code must retain the above copyright
8 - notice, this list of conditions and the following disclaimer.
9 - 2. Redistributions in binary form must reproduce the above
10 - copyright notice, this list of conditions and the following
11 - disclaimer in the documentation and/or other materials
12 - provided with the distribution.
13 -
14 - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
15 - ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
16 - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
17 - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ANY
18 - CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
19 - EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
20 - PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
21 - PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
22 - OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
23 - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
24 - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25 *====================================================================*/
26
27 style-guide.txt
28
29 10 May 2019
30
31 This is not a complete guide to the coding style in leptonica.
32 It covers most of the typographic issues and the most frequent
33 coding patterns, such as how to check input args to functions.
34 In general, you need to look at existing code to verify that your
35 code meets the style guidelines. And if you find any aberrant code,
36 please let me know!
37
38 The C code in leptonica follows these conventions:
39
40 (1) ANSI C, with no exceptions
41
42 (a) C-style comments only: /* */
43
44 (b) Variables are declared at the beginning of a function.
45 [This is more strict than ANSI C, which only requires declarations
46 to be at the beginning of a scope delineated by braces.]
47
48 (c) Use typedefs for structs like Pix; e.g.,
49 function(PIX *pixs)
50 Do not do this (omitting the 'struct' keyword); it is valid C++,
51 but not C:
52 function(Pix *pixs)
53
54 (2) Formatting
55
56 (a) White space: 4 space indentation. No tabs, ever. No trailing spaces.
57
58 (b) The code is set up to work with doxygen. Function headers are in
59 this format:
60
61 /*!
62 * \brief pixSelectByAreaFraction()
63 *
64 * \param[in] pixs 1 bpp
65 * \param[in] thresh threshold ratio of fg pixels to (w * h)
66 * \param[in] connectivity 4 or 8
67 * \param[in] type L_SELECT_IF_LT, L_SELECT_IF_GT,
68 * L_SELECT_IF_LTE, L_SELECT_IF_GTE
69 * \param[out] pchanged [optional] 1 if changed; 0 if clone returned
70 * \return pixd, or NULL on error
71 *
72 * <pre>
73 * Notes:
74 * (1) The args specify constraints on the amount of foreground
75 * coverage of the components that are kept.
76 * ....
77 * </pre>
78 */
79
80 (c) Function definition has return value on separate line and starting
81 brace on separate line.
82
83 PIX *
84 function(...)
85 {
86
87 (d) Function arguments and local variables line up vertically;
88 allow at least 2 spaces between type and variable name (including '*')
89
90 function(PIX *pixs,
91 l_int32 factor,
92 l_float32 *pave)
93 {
94 char buf[BUF_SIZE];
95 l_int32 w, h, d;
96 l_float32 *vect;
97
98 (e) Braces are placed like this for 'if', 'while', 'do':
99
100 if (...) {
101 ...
102 } else if (...) {
103 ...
104 }
105
106 The exceptions are for the beginning of a function and for the switch:
107
108 switch (x)
109 {
110 case 1:
111 ...
112 ...
113 }
114
115 Braces are required if any of the clauses have more than one statement:
116
117 if (...) {
118 x = 0;
119 } else {
120 x++;
121 y = 3.0 * x;
122 }
123
124 (f) Section headers should look like this:
125
126 /*----------------------------------------------------------------------*
127 * Statistics in an arbitrary rectangle *
128 *----------------------------------------------------------------------*/
129
130 (g) Major inline comments (starting a section) should be indented
131 4 extra spaces and start with a capital. Multiple line comments
132 should be formatted like this:
133
134 /* If w and h not input, determine the minimum size required
135 * to contain the origin and all c.c. */
136
137 (h) Minor inline comments (e.g., at the end of a line) should have
138 2 spaces and no leading capital; e.g.
139
140 if (i && ((i % ncols) == 0)) { /* start new row */
141
142 (3) Naming
143
144 (a) Function names begin with lower case and successive words have
145 the first letter capitalized; e.g., boxIntersects().
146
147 (b) The first word in the function name is the name of the primary
148 input data structure (if there is one); otherwise it can
149 name the output data structure (if there is one).
150
151 (c) Variable names are as short as possible, without causing confusion.
152
153 (d) Pointers to data structures are typically named by the type of
154 struct, without a leading 'p'; e.g., pixt, boxt.
155
156 (e) When ptrs are input to a function, in order to return a value,
157 if the local name would be 'ave', the pointer is 'pave'.
158
159 (f) Preprocessor variables and enums are named all caps,
160 with '_' between parts.
161
162 (g) Static constants defined in a file should have the first letter of
163 each word capitalized. (There are also some that are formatted
164 like enums, with all caps and '_' between parts.)
165
166 (h) There are very few globals in the library. Of these, there
167 are just a handful of static globals that can be changed.
168 Const globals are named with each word beginning with a capital; e.g.,
169 ImageFileFormatExtensions[]
170 Static globals that can be changed are named like preprocessor
171 variables, except they are prepended by 'var_'; e.g.,
172 var_PNG_WRITE_ALPHA
173 Functions that set these static globals are named with a
174 pre-pended 'l_'; e.g.,
175 l_pngSetWriteAlpha()
176
177 (i) Where there may be issues with namespace collisions with other
178 libraries, function names can be prepended with 'l_'; e.g.,
179 l_amapInsert()
180
181 (4) Arg checking
182
183 Both number values and ptrs can be returned in function arguments.
184 The following applies equally to both types, and happens at the
185 beginning of the function. We distinguish between returned entities
186 that are optional and required. The following sequence of tests
187 and initializations guarantees that no uninitialized arguments
188 are returned:
189
190 (a) First, all optional values are initialized if possible:
191
192 if (pboxa) *pboxa = NULL; // Boxa **pboxa is optional
193
194 (b) Second, if there is more than 1 required value, each is
195 initialized if possible:
196
197 if (pnar) *pnar = NULL; // Numa **pnar is required
198 if (pnag) *pnag = NULL; // Numa **pnag is required
199
200 Then all required arguments are tested in arbitrary order.
201
202 But if there is exactly 1 required value, it can be checked
203 and initialized if possible:
204
205 if (!ppixd)
206 return ERROR_INT("&pixd not defined, procName, 1);
207 *ppixd = NULL;
208
209 (5) Miscellaneous
210
211 (a) Look around at the code after reviewing the guidelines.
212
213 (b) Return nothing on stdout.
214
215 (c) Returns to stderr should be blockable by compiler flags, such
216 as NO_CONSOLE_IO, and by setting message severity thresholds
217 both at compile and at run time. Naked fprintf(stderr, ...)
218 should be avoided in the library.
219
220 (d) Applications (in prog) that hand a FILE ptr to a library function,
221 or accept heap-allocated data from a library function, should
222 use special wrappers. See lept_*() functions in utils.c.
223
224 (e) Changes to existing data structures and API changes should be
225 avoided if possible.
226
227 (f) Accessors are typically provided for struct fields that have
228 extensive use.
229
230