diff options
Diffstat (limited to 'Documentation/translations/it_IT/doc-guide/kernel-doc.rst')
| -rw-r--r-- | Documentation/translations/it_IT/doc-guide/kernel-doc.rst | 113 |
1 files changed, 83 insertions, 30 deletions
diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst index a4ecd8f27631..aa0e31d353d6 100644 --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst @@ -3,8 +3,11 @@ .. note:: Per leggere la documentazione originale in inglese: :ref:`Documentation/doc-guide/index.rst <doc_guide>` +.. title:: Commenti in kernel-doc + .. _it_kernel_doc: +================================= Scrivere i commenti in kernel-doc ================================= @@ -177,9 +180,9 @@ Il valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome se provate a formattare bene il vostro testo come nel seguente esempio:: * Return: - * 0 - OK - * -EINVAL - invalid argument - * -ENOMEM - out of memory + * %0 - OK + * %-EINVAL - invalid argument + * %-ENOMEM - out of memory le righe verranno unite e il risultato sarà:: @@ -189,8 +192,8 @@ Il valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome utilizzare una lista ReST, ad esempio:: * Return: - * * 0 - OK to runtime suspend the device - * * -EBUSY - Device should not be runtime suspended + * * %0 - OK to runtime suspend the device + * * %-EBUSY - Device should not be runtime suspended #) Se il vostro testo ha delle righe che iniziano con una frase seguita dai due punti, allora ognuna di queste frasi verrà considerata come il nome @@ -367,6 +370,50 @@ Anche i tipi di dato per prototipi di funzione possono essere documentati:: */ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); +Documentazione di macro simili a oggetti +---------------------------------------- + +Le macro simili a oggetti si distinguono dalle macro simili a funzione. Esse si +distinguono in base al fatto che il nome della macro simile a funzione sia +immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a +oggetti no. + +Le macro simili a funzioni sono gestite come funzioni da ``scripts/kernel-doc``. +Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un +elenco di parametri. + +Il formato generale di un commento kernel-doc per una macro simile a oggetti è:: + + /** + * define object_name - Brief description. + * + * Description of the object. + */ + +Esempio:: + + /** + * define MAX_ERRNO - maximum errno value that is supported + * + * Kernel pointers have redundant information, so we can use a + * scheme where we can return either an error code or a normal + * pointer with the same return value. + */ + #define MAX_ERRNO 4095 + +Esempio:: + + /** + * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ + * Initializes struct drm_plane_helper_funcs for VRAM handling + * + * This macro initializes struct drm_plane_helper_funcs to use the + * respective helper functions. + */ + #define DRM_GEM_VRAM_PLANE_HELPER_FUNCS \ + .prepare_fb = drm_gem_vram_plane_helper_prepare_fb, \ + .cleanup_fb = drm_gem_vram_plane_helper_cleanup_fb + Marcatori e riferimenti ----------------------- @@ -419,26 +466,24 @@ del `dominio Sphinx per il C`_. Riferimenti usando reStructuredText ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Per fare riferimento a funzioni e tipi di dato definiti nei commenti kernel-doc -all'interno dei documenti reStructuredText, utilizzate i riferimenti dal -`dominio Sphinx per il C`_. Per esempio:: - - See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`. +Nei documenti reStructuredText non serve alcuna sintassi speciale per +fare riferimento a funzioni e tipi definiti nei commenti +kernel-doc. Sarà sufficiente terminare i nomi di funzione con ``()``, +e scrivere ``struct``, ``union``, ``enum``, o ``typedef`` prima di un +tipo. Per esempio:: -Nonostante il riferimento ai tipi di dato funzioni col solo nome, -ovvero senza specificare struct/union/enum/typedef, potreste preferire il -seguente:: + See foo() + See struct foo. + See union bar. + See enum baz. + See typedef meh. - See :c:type:`struct foo <foo>`. - See :c:type:`union bar <bar>`. - See :c:type:`enum baz <baz>`. - See :c:type:`typedef meh <meh>`. +Tuttavia, la personalizzazione dei collegamenti è possibile solo con +la seguente sintassi:: -Questo produce dei collegamenti migliori, ed è in linea con il modo in cui -kernel-doc gestisce i riferimenti. + See :c:func:`my custom link text for function foo <foo>`. + See :c:type:`my custom link text for struct bar <bar>`. -Per maggiori informazioni, siete pregati di consultare la documentazione -del `dominio Sphinx per il C`_. Commenti per una documentazione generale ---------------------------------------- @@ -471,6 +516,7 @@ Il titolo che segue ``DOC:`` funziona da intestazione all'interno del file sorgente, ma anche come identificatore per l'estrazione di questi commenti di documentazione. Quindi, il titolo dev'essere unico all'interno del file. +======================================= Includere i commenti di tipo kernel-doc ======================================= @@ -515,6 +561,22 @@ internal: *[source-pattern ...]* .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :internal: +identifiers: *[ function/type ...]* + Include la documentazione per ogni *function* e *type* in *source*. + Se non vengono esplicitamente specificate le funzioni da includere, allora + verranno incluse tutte quelle disponibili in *source*. + + Esempi:: + + .. kernel-doc:: lib/bitmap.c + :identifiers: bitmap_parselist bitmap_parselist_user + + .. kernel-doc:: lib/idr.c + :identifiers: + +functions: *[ function ...]* + Questo è uno pseudonimo, deprecato, per la direttiva 'identifiers'. + doc: *title* Include la documentazione del paragrafo ``DOC:`` identificato dal titolo (*title*) all'interno del file sorgente (*source*). Gli spazi in *title* sono @@ -528,15 +590,6 @@ doc: *title* .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :doc: High Definition Audio over HDMI and Display Port -functions: *function* *[...]* - Dal file sorgente (*source*) include la documentazione per le funzioni - elencate (*function*). - - Esempio:: - - .. kernel-doc:: lib/bitmap.c - :functions: bitmap_parselist bitmap_parselist_user - Senza alcuna opzione, la direttiva kernel-doc include tutti i commenti di documentazione presenti nel file sorgente (*source*). |