it_IT/doc-guide/kernel-doc.rst

1 .. include:: ../disclaimer-ita.rst
3 .. note:: Per leggere la documentazione originale in inglese:
4 	  :ref:`Documentation/doc-guide/index.rst <doc_guide>`
8 Scrivere i commenti in kernel-doc
12 strutturanti secondo il formato kernel-doc. Essi possono descrivere funzioni,
15 .. note:: Il formato kernel-doc può sembrare simile a gtk-doc o Doxygen ma
16    in realtà è molto differente per ragioni storiche. I sorgenti del kernel
17    contengono decine di migliaia di commenti kernel-doc. Siete pregati
20 La struttura kernel-doc è estratta a partire dai commenti; da questi viene
21 generato il `dominio Sphinx per il C`_ con un'adeguata descrizione per le
23 vengono filtrare per cercare i riferimenti ed i marcatori.
25 Vedere di seguito per maggiori dettagli.
27 .. _`dominio Sphinx per il C`: http://www.sphinx-doc.org/en/stable/domains.html
31 kernel-doc. Quando l'intenzione è di utilizzarle nei moduli, anche le funzioni
33 kernel-doc.
36 secondo kernel-doc per le funzioni che sono visibili da altri file del kernel
38 inoltre, di fornire una documentazione kernel-doc anche per procedure private
45 Sicuramente la documentazione formattata con kernel-doc è necessaria per
49 Cerchiamo anche di fornire una documentazione formattata secondo kernel-doc
50 per le funzioni che sono visibili da altri file del kernel (ovvero, che non
53 Raccomandiamo, inoltre, di fornire una documentazione formattata con kernel-doc
54 anche per procedure private (ovvero, dichiarate "static") al fine di fornire
59 documentate utilizzando commenti formattati con kernel-doc.
61 Come formattare i commenti kernel-doc
62 -------------------------------------
64 I commenti kernel-doc iniziano con il marcatore ``/**``. Il programma
65 ``kernel-doc`` estrarrà i commenti marchiati in questo modo. Il resto
70 I commenti kernel-doc di funzioni e tipi dovrebbero essere posizionati
73 anche la documentazione. I commenti kernel-doc di tipo più generale possono
77 eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza
78 che questo produca alcuna documentazione. Per esempio::
80 	scripts/kernel-doc -v -none drivers/foo/bar.c
88 ------------------------
90 Generalmente il formato di un commento kernel-doc per funzioni e
91 macro simil-funzioni è il seguente::
94    * function_name() - Brief description of function.
107    * Context: Describes whether the function can sleep, what locks it takes,
145 dovrebbe essere scritta con la notazione kernel-doc::
153 sezione chiamata ``Context``. Questo dovrebbe informare sulla possibilità
160   * Context: Any context.
161   * Context: Any context. Takes and releases the RCU lock.
162   * Context: Any context. Expects <lock> to be held by caller.
163   * Context: Process context. May sleep if @gfp flags permit.
164   * Context: Process context. Takes and releases <mutex>.
165   * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
166   * Context: Interrupt context.
176   #) La descrizione multiriga non riconosce il termine d'una riga, per cui
180 	* 0 - OK
181 	* -EINVAL - invalid argument
182 	* -ENOMEM - out of memory
186 	Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
192       * * 0		- OK to runtime suspend the device
193       * * -EBUSY	- Device should not be runtime suspended
200 ---------------------------------------------
202 Generalmente il formato di un commento kernel-doc per struct, union ed enum è::
205    * struct struct_name - Brief description.
215 per descrivere unioni ed enumerati. ``member`` viene usato per indicare i
240    * struct my_struct - short description
262        * struct nested_foobar - a struct with nested unions and structs
267        * @bar: non-anonymous union
307 Commenti in linea per la documentazione dei membri
313 qualsiasi altro commento kernel-doc::
316    * struct foo - Brief description.
346 -------------------------------
347 Generalmente il formato di un commento kernel-doc per typedef è
351    * typedef type_name - Brief description.
356 Anche i tipi di dato per prototipi di funzione possono essere documentati::
359    * typedef type_name - Brief description.
365    * Context: Locking context.
371 -----------------------
373 All'interno dei commenti di tipo kernel-doc vengono riconosciuti i seguenti
375 del `dominio Sphinx per il C`_.
378                kernel-doc, e **non** all'interno di documenti reStructuredText.
394   potrebbero assumere un significato diverso in kernel-doc o in reStructuredText
411 ``&struct_name->member`` or ``&struct_name.member``
422 Per fare riferimento a funzioni e tipi di dato definiti nei commenti kernel-doc
424 `dominio Sphinx per il C`_. Per esempio::
438 kernel-doc gestisce i riferimenti.
440 Per maggiori informazioni, siete pregati di consultare la documentazione
441 del `dominio Sphinx per il C`_.
443 Commenti per una documentazione generale
444 ----------------------------------------
447 dei blocchi di documentazione kernel-doc con un formato libero invece
448 che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi
449 di dato. Per esempio, questo tipo di commento potrebbe essere usato per la
471 sorgente, ma anche come identificatore per l'estrazione di questi commenti di
474 Includere i commenti di tipo kernel-doc
479 kernel-doc per Sphinx.
481 Le direttive kernel-doc sono nel formato::
483   .. kernel-doc:: source
489 export: *[source-pattern ...]*
490   Include la documentazione per tutte le funzioni presenti nel file sorgente
492   ``EXPORT_SYMBOL_GPL`` in *source* o in qualsiasi altro *source-pattern*
495   Il campo *source-patter* è utile quando i commenti kernel-doc sono stati
501     .. kernel-doc:: lib/bitmap.c
504     .. kernel-doc:: include/net/mac80211.h
507 internal: *[source-pattern ...]*
508   Include la documentazione per tutte le funzioni ed i tipi presenti nel file
511   altro *source-pattern* specificato.
515     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
519   Include la documentazione per ogni *function* e *type*  in *source*.
525     .. kernel-doc:: lib/bitmap.c
528     .. kernel-doc:: lib/idr.c
532   Questo è uno pseudonimo, deprecato, per la direttiva 'identifiers'.
537   permessi; non virgolettate *title*. Il campo *title* è utilizzato per
538   identificare un paragrafo e per questo non viene incluso nella documentazione
544     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
547 Senza alcuna opzione, la direttiva kernel-doc include tutti i commenti di
550 L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare
552 lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione
555 Come utilizzare kernel-doc per generare pagine man
556 --------------------------------------------------
558 Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
561 …$ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl…