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>`
6 .. title:: Commenti in kernel-doc
11 Scrivere i commenti in kernel-doc
15 strutturanti secondo il formato kernel-doc. Essi possono descrivere funzioni,
18 .. note:: Il formato kernel-doc può sembrare simile a gtk-doc o Doxygen ma
19    in realtà è molto differente per ragioni storiche. I sorgenti del kernel
20    contengono decine di migliaia di commenti kernel-doc. Siete pregati
23 La struttura kernel-doc è estratta a partire dai commenti; da questi viene
24 generato il `dominio Sphinx per il C`_ con un'adeguata descrizione per le
26 vengono filtrare per cercare i riferimenti ed i marcatori.
28 Vedere di seguito per maggiori dettagli.
30 .. _`dominio Sphinx per il C`: http://www.sphinx-doc.org/en/stable/domains.html
34 kernel-doc. Quando l'intenzione è di utilizzarle nei moduli, anche le funzioni
36 kernel-doc.
39 secondo kernel-doc per le funzioni che sono visibili da altri file del kernel
41 inoltre, di fornire una documentazione kernel-doc anche per procedure private
48 Sicuramente la documentazione formattata con kernel-doc è necessaria per
52 Cerchiamo anche di fornire una documentazione formattata secondo kernel-doc
53 per le funzioni che sono visibili da altri file del kernel (ovvero, che non
56 Raccomandiamo, inoltre, di fornire una documentazione formattata con kernel-doc
57 anche per procedure private (ovvero, dichiarate "static") al fine di fornire
62 documentate utilizzando commenti formattati con kernel-doc.
64 Come formattare i commenti kernel-doc
65 -------------------------------------
67 I commenti kernel-doc iniziano con il marcatore ``/**``. Il programma
68 ``kernel-doc`` estrarrà i commenti marchiati in questo modo. Il resto
73 I commenti kernel-doc di funzioni e tipi dovrebbero essere posizionati
76 anche la documentazione. I commenti kernel-doc di tipo più generale possono
80 eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza
81 che questo produca alcuna documentazione. Per esempio::
83 	scripts/kernel-doc -v -none drivers/foo/bar.c
91 ------------------------
93 Generalmente il formato di un commento kernel-doc per funzioni e
94 macro simil-funzioni è il seguente::
97    * function_name() - Brief description of function.
110    * Context: Describes whether the function can sleep, what locks it takes,
148 dovrebbe essere scritta con la notazione kernel-doc::
156 sezione chiamata ``Context``. Questo dovrebbe informare sulla possibilità
163   * Context: Any context.
164   * Context: Any context. Takes and releases the RCU lock.
165   * Context: Any context. Expects <lock> to be held by caller.
166   * Context: Process context. May sleep if @gfp flags permit.
167   * Context: Process context. Takes and releases <mutex>.
168   * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
169   * Context: Interrupt context.
179   #) La descrizione multiriga non riconosce il termine d'una riga, per cui
183 	* %0 - OK
184 	* %-EINVAL - invalid argument
185 	* %-ENOMEM - out of memory
189 	Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
195       * * %0		- OK to runtime suspend the device
196       * * %-EBUSY	- Device should not be runtime suspended
203 ---------------------------------------------
205 Generalmente il formato di un commento kernel-doc per struct, union ed enum è::
208    * struct struct_name - Brief description.
218 per descrivere unioni ed enumerati. ``member`` viene usato per indicare i
243    * struct my_struct - short description
265        * struct nested_foobar - a struct with nested unions and structs
270        * @bar: non-anonymous union
310 Commenti in linea per la documentazione dei membri
316 qualsiasi altro commento kernel-doc::
319    * struct foo - Brief description.
349 -------------------------------
350 Generalmente il formato di un commento kernel-doc per typedef è
354    * typedef type_name - Brief description.
359 Anche i tipi di dato per prototipi di funzione possono essere documentati::
362    * typedef type_name - Brief description.
368    * Context: Locking context.
374 ----------------------------------------
381 Le macro simili a funzioni sono gestite come funzioni da ``scripts/kernel-doc``.
385 Il formato generale di un commento kernel-doc per una macro simile a oggetti è::
388    * define object_name - Brief description.
396    * define MAX_ERRNO - maximum errno value that is supported
407    * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \
418 -----------------------
420 All'interno dei commenti di tipo kernel-doc vengono riconosciuti i seguenti
422 del `dominio Sphinx per il C`_.
425                kernel-doc, e **non** all'interno di documenti reStructuredText.
441   potrebbero assumere un significato diverso in kernel-doc o in reStructuredText
458 ``&struct_name->member`` or ``&struct_name.member``
469 Nei documenti reStructuredText non serve alcuna sintassi speciale per
471 kernel-doc. Sarà sufficiente terminare i nomi di funzione con ``()``,
473 tipo. Per esempio::
488 Commenti per una documentazione generale
489 ----------------------------------------
492 dei blocchi di documentazione kernel-doc con un formato libero invece
493 che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi
494 di dato. Per esempio, questo tipo di commento potrebbe essere usato per la
516 sorgente, ma anche come identificatore per l'estrazione di questi commenti di
520 Includere i commenti di tipo kernel-doc
525 kernel-doc per Sphinx.
527 Le direttive kernel-doc sono nel formato::
529   .. kernel-doc:: source
535 export: *[source-pattern ...]*
536   Include la documentazione per tutte le funzioni presenti nel file sorgente
538   ``EXPORT_SYMBOL_GPL`` in *source* o in qualsiasi altro *source-pattern*
541   Il campo *source-patter* è utile quando i commenti kernel-doc sono stati
547     .. kernel-doc:: lib/bitmap.c
550     .. kernel-doc:: include/net/mac80211.h
553 internal: *[source-pattern ...]*
554   Include la documentazione per tutte le funzioni ed i tipi presenti nel file
557   altro *source-pattern* specificato.
561     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
565   Include la documentazione per ogni *function* e *type*  in *source*.
571     .. kernel-doc:: lib/bitmap.c
574     .. kernel-doc:: lib/idr.c
578   Questo è uno pseudonimo, deprecato, per la direttiva 'identifiers'.
583   permessi; non virgolettate *title*. Il campo *title* è utilizzato per
584   identificare un paragrafo e per questo non viene incluso nella documentazione
590     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
593 Senza alcuna opzione, la direttiva kernel-doc include tutti i commenti di
596 L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare
598 lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione
601 Come utilizzare kernel-doc per generare pagine man
602 --------------------------------------------------
604 Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
607 …$ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl…