1.. include:: ../disclaimer-ita.rst
2
3:Original: Documentation/doc-guide/index.rst
4
5=========================================
6Includere gli i file di intestazione uAPI
7=========================================
8
9Qualche volta è utile includere dei file di intestazione e degli esempi di codice C
10al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti
11fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API
12dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi
13d'avviso se un simbolo non viene trovato nella documentazione. Questo permette
14di mantenere allineate la documentazione della uAPI (API spazio utente)
15con le modifiche del kernel.
16Il programma :ref:`parse_headers.pl <it_parse_headers>` genera questi riferimenti.
17Esso dev'essere invocato attraverso un Makefile, mentre si genera la
18documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel
19consultate ``Documentation/userspace-api/media/Makefile``.
20
21.. _it_parse_headers:
22
23parse_headers.pl
24^^^^^^^^^^^^^^^^
25
26NOME
27****
28
29
30parse_headers.pl - analizza i file C al fine di identificare funzioni,
31strutture, enumerati e definizioni, e creare riferimenti per Sphinx
32
33SINTASSI
34********
35
36
37\ **parse_headers.pl**\  [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
38
39Dove <options> può essere: --debug, --usage o --help.
40
41
42OPZIONI
43*******
44
45
46
47\ **--debug**\
48
49 Lo script viene messo in modalità verbosa, utile per il debugging.
50
51
52\ **--usage**\
53
54 Mostra un messaggio d'aiuto breve e termina.
55
56
57\ **--help**\
58
59 Mostra un messaggio d'aiuto dettagliato e termina.
60
61
62DESCRIZIONE
63***********
64
65Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo
66ReStructuredText incluso mediante il blocco ..parsed-literal
67con riferimenti alla documentazione che descrive l'API. Opzionalmente,
68il programma accetta anche un altro file (EXCEPTIONS_FILE) che
69descrive quali elementi debbano essere ignorati o il cui riferimento
70deve puntare ad elemento diverso dal predefinito.
71
72Il file generato sarà disponibile in (OUT_FILE).
73
74Il programma è capace di identificare *define*, funzioni, strutture,
75tipi di dato, enumerati e valori di enumerati, e di creare i riferimenti
76per ognuno di loro. Inoltre, esso è capace di distinguere le #define
77utilizzate per specificare i comandi ioctl di Linux.
78
79Il file EXCEPTIONS_FILE contiene due tipi di dichiarazioni:
80\ **ignore**\  o \ **replace**\ .
81
82La sintassi per ignore è:
83
84ignore \ **tipo**\  \ **nome**\
85
86La dichiarazione \ **ignore**\  significa che non verrà generato alcun
87riferimento per il simbolo \ **name**\  di tipo \ **tipo**\ .
88
89
90La sintassi per replace è:
91
92replace \ **tipo**\  \ **nome**\  \ **nuovo_valore**\
93
94La dichiarazione \ **replace**\  significa che verrà generato un
95riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ , ma, invece
96di utilizzare il valore predefinito, verrà utilizzato il valore
97\ **nuovo_valore**\ .
98
99Per entrambe le dichiarazioni, il \ **tipo**\  può essere uno dei seguenti:
100
101
102\ **ioctl**\
103
104 La dichiarazione ignore o replace verrà applicata su definizioni di ioctl
105 come la seguente:
106
107 #define	VIDIOC_DBG_S_REGISTER 	 _IOW('V', 79, struct v4l2_dbg_register)
108
109
110
111\ **define**\
112
113 La dichiarazione ignore o replace verrà applicata su una qualsiasi #define
114 trovata in C_FILE.
115
116
117
118\ **typedef**\
119
120 La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef
121 in C_FILE.
122
123
124
125\ **struct**\
126
127 La dichiarazione ignore o replace verrà applicata ai nomi di strutture
128 in C_FILE.
129
130
131
132\ **enum**\
133
134 La dichiarazione ignore o replace verrà applicata ai nomi di enumerati
135 in C_FILE.
136
137
138
139\ **symbol**\
140
141 La dichiarazione ignore o replace verrà applicata ai nomi di valori di
142 enumerati in C_FILE.
143
144 Per le dichiarazioni di tipo replace, il campo \ **new_value**\  utilizzerà
145 automaticamente i riferimenti :c:type: per \ **typedef**\ , \ **enum**\  e
146 \ **struct**\. Invece, utilizzerà :ref: per \ **ioctl**\ , \ **define**\  e
147 \ **symbol**\. Il tipo di riferimento può essere definito esplicitamente
148 nella dichiarazione stessa.
149
150
151ESEMPI
152******
153
154
155ignore define _VIDEODEV2_H
156
157
158Ignora una definizione #define _VIDEODEV2_H nel file C_FILE.
159
160ignore symbol PRIVATE
161
162
163In un enumerato come il seguente:
164
165enum foo { BAR1, BAR2, PRIVATE };
166
167Non genererà alcun riferimento per \ **PRIVATE**\ .
168
169replace symbol BAR1 :c:type:\`foo\`
170replace symbol BAR2 :c:type:\`foo\`
171
172
173In un enumerato come il seguente:
174
175enum foo { BAR1, BAR2, PRIVATE };
176
177Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C.
178
179
180BUGS
181****
182
183Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com>
184
185
186COPYRIGHT
187*********
188
189
190Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
191
192Licenza GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
193
194Questo è software libero: siete liberi di cambiarlo e ridistribuirlo.
195Non c'è alcuna garanzia, nei limiti permessi dalla legge.
196