sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextEnglish}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget/doc-guide/kernel-docmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Simplified)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/zh_CN/doc-guide/kernel-docmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hChinese (Traditional)}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/zh_TW/doc-guide/kernel-docmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ja_JP/doc-guide/kernel-docmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ko_KR/doc-guide/kernel-docmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/sp_SP/doc-guide/kernel-docmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageItalianuh1h hh _documenthsourceNlineNubhwarning)}(hIn caso di dubbi sulla correttezza del contenuto di questa traduzione, l'unico riferimento valido è la documentazione ufficiale in inglese. Per maggiori informazioni consultate le :ref:`avvertenze `.h]h paragraph)}(hIn caso di dubbi sulla correttezza del contenuto di questa traduzione, l'unico riferimento valido è la documentazione ufficiale in inglese. Per maggiori informazioni consultate le :ref:`avvertenze `.h](hIn caso di dubbi sulla correttezza del contenuto di questa traduzione, l’unico riferimento valido è la documentazione ufficiale in inglese. Per maggiori informazioni consultate le }(hhhhhNhNubh)}(h!:ref:`avvertenze `h]hinline)}(hhh]h avvertenze}(hhhhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1hhhubah}(h]h ]h"]h$]h&]refdoc'translations/it_IT/doc-guide/kernel-doc refdomainhŒreftyperef refexplicitrefwarn reftarget it_disclaimeruh1hh3Documentation/translations/it_IT/disclaimer-ita.rsthKhhubh.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubhnote)}(hhPer leggere la documentazione originale in inglese: :ref:`Documentation/doc-guide/index.rst `h]h)}(hhPer leggere la documentazione originale in inglese: :ref:`Documentation/doc-guide/index.rst `h](h4Per leggere la documentazione originale in inglese: }(hhhhhNhNubh)}(h4:ref:`Documentation/doc-guide/index.rst `h]h)}(hhh]h!Documentation/doc-guide/index.rst}(hhhhhNhNubah}(h]h ](hstdstd-refeh"]h$]h&]uh1hhhubah}(h]h ]h"]h$]h&]refdochΌ refdomainjreftyperef refexplicitrefwarnhԌ doc_guideuh1hhU/var/lib/git/docbuild/linux/Documentation/translations/it_IT/doc-guide/kernel-doc.rsthKhhubeh}(h]h ]h"]h$]h&]uh1hhjhKhhubah}(h]h ]h"]h$]h&]uh1hhhhhhjhNubhtarget)}(h.. _it_kernel_doc:h]h}(h]h ]h"]h$]h&]refid it-kernel-docuh1j"hKhhhhhjubhsection)}(hhh](htitle)}(h!Scrivere i commenti in kernel-doch]h!Scrivere i commenti in kernel-doc}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj2hhhjhK ubh)}(hNei file sorgenti del kernel Linux potrete trovare commenti di documentazione strutturanti secondo il formato kernel-doc. Essi possono descrivere funzioni, tipi di dati, e l'architettura del codice.h]hNei file sorgenti del kernel Linux potrete trovare commenti di documentazione strutturanti secondo il formato kernel-doc. Essi possono descrivere funzioni, tipi di dati, e l’architettura del codice.}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhj2hhubh)}(hIl formato kernel-doc può sembrare simile a gtk-doc o Doxygen ma in realtà è molto differente per ragioni storiche. I sorgenti del kernel contengono decine di migliaia di commenti kernel-doc. Siete pregati d'attenervi allo stile qui descritto.h]h)}(hIl formato kernel-doc può sembrare simile a gtk-doc o Doxygen ma in realtà è molto differente per ragioni storiche. I sorgenti del kernel contengono decine di migliaia di commenti kernel-doc. Siete pregati d'attenervi allo stile qui descritto.h]hIl formato kernel-doc può sembrare simile a gtk-doc o Doxygen ma in realtà è molto differente per ragioni storiche. I sorgenti del kernel contengono decine di migliaia di commenti kernel-doc. Siete pregati d’attenervi allo stile qui descritto.}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjSubah}(h]h ]h"]h$]h&]uh1hhj2hhhjhNubh)}(hXLa struttura kernel-doc è estratta a partire dai commenti; da questi viene generato il `dominio Sphinx per il C`_ con un'adeguata descrizione per le funzioni ed i tipi di dato con i loro relativi collegamenti. Le descrizioni vengono filtrare per cercare i riferimenti ed i marcatori.h](hXLa struttura kernel-doc è estratta a partire dai commenti; da questi viene generato il }(hjkhhhNhNubh reference)}(h`dominio Sphinx per il C`_h]hdominio Sphinx per il C}(hjuhhhNhNubah}(h]h ]h"]h$]h&]namedominio Sphinx per il Crefuri0http://www.sphinx-doc.org/en/stable/domains.htmluh1jshjkresolvedKubh con un’adeguata descrizione per le funzioni ed i tipi di dato con i loro relativi collegamenti. Le descrizioni vengono filtrare per cercare i riferimenti ed i marcatori.}(hjkhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhKhj2hhubh)}(h(Vedere di seguito per maggiori dettagli.h]h(Vedere di seguito per maggiori dettagli.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhj2hhubj#)}(hO.. _`dominio Sphinx per il C`: http://www.sphinx-doc.org/en/stable/domains.htmlh]h}(h]dominio-sphinx-per-il-cah ]h"]dominio sphinx per il cah$]h&]jjuh1j"hK(hj2hhhj referencedKubh)}(hX+Tutte le funzioni esportate verso i moduli esterni utilizzando ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` dovrebbero avere un commento kernel-doc. Quando l'intenzione è di utilizzarle nei moduli, anche le funzioni e le strutture dati nei file d'intestazione dovrebbero avere dei commenti kernel-doc.h](h?Tutte le funzioni esportate verso i moduli esterni utilizzando }(hjhhhNhNubhliteral)}(h``EXPORT_SYMBOL``h]h EXPORT_SYMBOL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh o }(hjhhhNhNubj)}(h``EXPORT_SYMBOL_GPL``h]hEXPORT_SYMBOL_GPL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh dovrebbero avere un commento kernel-doc. Quando l’intenzione è di utilizzarle nei moduli, anche le funzioni e le strutture dati nei file d’intestazione dovrebbero avere dei commenti kernel-doc.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhK hj2hhubh)}(hXÈ considerata una buona pratica quella di fornire una documentazione formattata secondo kernel-doc per le funzioni che sono visibili da altri file del kernel (ovvero, che non siano dichiarate utilizzando ``static``). Raccomandiamo, inoltre, di fornire una documentazione kernel-doc anche per procedure private (ovvero, dichiarate "static") al fine di fornire una struttura più coerente dei sorgenti. Quest'ultima raccomandazione ha una priorità più bassa ed è a discrezione dal manutentore (MAINTAINER) del file sorgente.h](hÈ considerata una buona pratica quella di fornire una documentazione formattata secondo kernel-doc per le funzioni che sono visibili da altri file del kernel (ovvero, che non siano dichiarate utilizzando }(hjhhhNhNubj)}(h ``static``h]hstatic}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX=). Raccomandiamo, inoltre, di fornire una documentazione kernel-doc anche per procedure private (ovvero, dichiarate “static”) al fine di fornire una struttura più coerente dei sorgenti. Quest’ultima raccomandazione ha una priorità più bassa ed è a discrezione dal manutentore (MAINTAINER) del file sorgente.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhK&hj2hhubh)}(hSicuramente la documentazione formattata con kernel-doc è necessaria per le funzioni che sono esportate verso i moduli esterni utilizzando ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL``.h](hSicuramente la documentazione formattata con kernel-doc è necessaria per le funzioni che sono esportate verso i moduli esterni utilizzando }(hjhhhNhNubj)}(h``EXPORT_SYMBOL``h]h EXPORT_SYMBOL}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh o }(hjhhhNhNubj)}(h``EXPORT_SYMBOL_GPL``h]hEXPORT_SYMBOL_GPL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhK0hj2hhubh)}(hCerchiamo anche di fornire una documentazione formattata secondo kernel-doc per le funzioni che sono visibili da altri file del kernel (ovvero, che non siano dichiarate utilizzando "static")h]hCerchiamo anche di fornire una documentazione formattata secondo kernel-doc per le funzioni che sono visibili da altri file del kernel (ovvero, che non siano dichiarate utilizzando “static”)}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK4hj2hhubh)}(hX=Raccomandiamo, inoltre, di fornire una documentazione formattata con kernel-doc anche per procedure private (ovvero, dichiarate "static") al fine di fornire una struttura più coerente dei sorgenti. Questa raccomandazione ha una priorità più bassa ed è a discrezione dal manutentore (MAINTAINER) del file sorgente.h]hXARaccomandiamo, inoltre, di fornire una documentazione formattata con kernel-doc anche per procedure private (ovvero, dichiarate “static”) al fine di fornire una struttura più coerente dei sorgenti. Questa raccomandazione ha una priorità più bassa ed è a discrezione dal manutentore (MAINTAINER) del file sorgente.}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK8hj2hhubh)}(hLe strutture dati visibili nei file di intestazione dovrebbero essere anch'esse documentate utilizzando commenti formattati con kernel-doc.h]hLe strutture dati visibili nei file di intestazione dovrebbero essere anch’esse documentate utilizzando commenti formattati con kernel-doc.}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK=hj2hhubj1)}(hhh](j6)}(h%Come formattare i commenti kernel-doch]h%Come formattare i commenti kernel-doc}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj]hhhjhKAubh)}(hX.I commenti kernel-doc iniziano con il marcatore ``/**``. Il programma ``kernel-doc`` estrarrà i commenti marchiati in questo modo. Il resto del commento è formattato come un normale commento multilinea, ovvero con un asterisco all'inizio d'ogni riga e che si conclude con ``*/`` su una riga separata.h](h0I commenti kernel-doc iniziano con il marcatore }(hjnhhhNhNubj)}(h``/**``h]h/**}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjnubh. Il programma }(hjnhhhNhNubj)}(h``kernel-doc``h]h kernel-doc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjnubh estrarrà i commenti marchiati in questo modo. Il resto del commento è formattato come un normale commento multilinea, ovvero con un asterisco all’inizio d’ogni riga e che si conclude con }(hjnhhhNhNubj)}(h``*/``h]h*/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjnubh su una riga separata.}(hjnhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhKChj]hhubh)}(hXMI commenti kernel-doc di funzioni e tipi dovrebbero essere posizionati appena sopra la funzione od il tipo che descrivono. Questo allo scopo di aumentare la probabilità che chi cambia il codice si ricordi di aggiornare anche la documentazione. I commenti kernel-doc di tipo più generale possono essere posizionati ovunque nel file.h]hXMI commenti kernel-doc di funzioni e tipi dovrebbero essere posizionati appena sopra la funzione od il tipo che descrivono. Questo allo scopo di aumentare la probabilità che chi cambia il codice si ricordi di aggiornare anche la documentazione. I commenti kernel-doc di tipo più generale possono essere posizionati ovunque nel file.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKIhj]hhubh)}(hAl fine di verificare che i commenti siano formattati correttamente, potete eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza che questo produca alcuna documentazione. Per esempio::h](hbAl fine di verificare che i commenti siano formattati correttamente, potete eseguire il programma }(hjhhhNhNubj)}(h``kernel-doc``h]h kernel-doc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubha con un livello di verbosità alto e senza che questo produca alcuna documentazione. Per esempio:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhKOhj]hhubh literal_block)}(h-scripts/kernel-doc -v -none drivers/foo/bar.ch]h-scripts/kernel-doc -v -none drivers/foo/bar.c}hjsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jhjhKShj]hhubh)}(hIl formato della documentazione è verificato della procedura di generazione del kernel quando viene richiesto di effettuare dei controlli extra con GCC::h]hIl formato della documentazione è verificato della procedura di generazione del kernel quando viene richiesto di effettuare dei controlli extra con GCC:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKUhj]hhubj)}(hmake W=nh]hmake W=n}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhKXhj]hhubeh}(h]%come-formattare-i-commenti-kernel-docah ]h"]%come formattare i commenti kernel-docah$]h&]uh1j0hj2hhhjhKAubj1)}(hhh](j6)}(hDocumentare le funzionih]hDocumentare le funzioni}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjhhhjhK[ubh)}(hfGeneralmente il formato di un commento kernel-doc per funzioni e macro simil-funzioni è il seguente::h]heGeneralmente il formato di un commento kernel-doc per funzioni e macro simil-funzioni è il seguente:}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK]hjhhubj)}(hX^/** * function_name() - Brief description of function. * @arg1: Describe the first argument. * @arg2: Describe the second argument. * One can provide multiple line descriptions * for arguments. * * A longer description, with more discussion of the function function_name() * that might be useful to those using or modifying it. Begins with an * empty comment line, and may include additional embedded empty * comment lines. * * The longer description may have multiple paragraphs. * * Context: Describes whether the function can sleep, what locks it takes, * releases, or expects to be held. It can extend over multiple * lines. * Return: Describe the return value of function_name. * * The return value description can also have multiple paragraphs, and should * be placed at the end of the comment block. */h]hX^/** * function_name() - Brief description of function. * @arg1: Describe the first argument. * @arg2: Describe the second argument. * One can provide multiple line descriptions * for arguments. * * A longer description, with more discussion of the function function_name() * that might be useful to those using or modifying it. Begins with an * empty comment line, and may include additional embedded empty * comment lines. * * The longer description may have multiple paragraphs. * * Context: Describes whether the function can sleep, what locks it takes, * releases, or expects to be held. It can extend over multiple * lines. * Return: Describe the return value of function_name. * * The return value description can also have multiple paragraphs, and should * be placed at the end of the comment block. */}hj5sbah}(h]h ]h"]h$]h&]jjuh1jhjhK`hjhhubh)}(hLa descrizione introduttiva (*brief description*) che segue il nome della funzione può continuare su righe successive e termina con la descrizione di un argomento, una linea di commento vuota, oppure la fine del commento.h](hLa descrizione introduttiva (}(hjChhhNhNubhemphasis)}(h*brief description*h]hbrief description}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjCubh) che segue il nome della funzione può continuare su righe successive e termina con la descrizione di un argomento, una linea di commento vuota, oppure la fine del commento.}(hjChhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhKwhjhhubj1)}(hhh](j6)}(hParametri delle funzionih]hParametri delle funzioni}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjehhhjhK|ubh)}(hOgni argomento di una funzione dovrebbe essere descritto in ordine, subito dopo la descrizione introduttiva. Non lasciare righe vuote né fra la descrizione introduttiva e quella degli argomenti, né fra gli argomenti.h]hOgni argomento di una funzione dovrebbe essere descritto in ordine, subito dopo la descrizione introduttiva. Non lasciare righe vuote né fra la descrizione introduttiva e quella degli argomenti, né fra gli argomenti.}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhK~hjehhubh)}(h2Ogni ``@argument:`` può estendersi su più righe.h](hOgni }(hjhhhNhNubj)}(h``@argument:``h]h @argument:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh può estendersi su più righe.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhKhjehhubh)}(hXDSe la descrizione di ``@argument:`` si estende su più righe, la continuazione dovrebbe iniziare alla stessa colonna della riga precedente:: * @argument: some long description * that continues on next lines or:: * @argument: * some long description * that continues on next linesh](h)}(hSe la descrizione di ``@argument:`` si estende su più righe, la continuazione dovrebbe iniziare alla stessa colonna della riga precedente::h](hSe la descrizione di }(hjhhhNhNubj)}(h``@argument:``h]h @argument:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhh si estende su più righe, la continuazione dovrebbe iniziare alla stessa colonna della riga precedente:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhKhjubj)}(hL* @argument: some long description * that continues on next linesh]hL* @argument: some long description * that continues on next lines}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhKhjubh)}(hor::h]hor:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubj)}(hS* @argument: * some long description * that continues on next linesh]hS* @argument: * some long description * that continues on next lines}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhKhjubeh}(h]h ]h"]h$]h&]uh1hhjehhhjhNubh)}(h}Se una funzione ha un numero variabile di argomento, la sua descrizione dovrebbe essere scritta con la notazione kernel-doc::h]h|Se una funzione ha un numero variabile di argomento, la sua descrizione dovrebbe essere scritta con la notazione kernel-doc:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjehhubj)}(h* @...: descriptionh]h* @...: description}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhKhjehhubeh}(h]parametri-delle-funzioniah ]h"]parametri delle funzioniah$]h&]uh1j0hjhhhjhK|ubj1)}(hhh](j6)}(hContesto delle funzionih]hContesto delle funzioni}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjhhhjhKubh)}(hXHIl contesto in cui le funzioni vengono chiamate viene descritto in una sezione chiamata ``Context``. Questo dovrebbe informare sulla possibilità che una funzione dorma (*sleep*) o che possa essere chiamata in un contesto d'interruzione, così come i *lock* che prende, rilascia e che si aspetta che vengano presi dal chiamante.h](hXIl contesto in cui le funzioni vengono chiamate viene descritto in una sezione chiamata }(hj-hhhNhNubj)}(h ``Context``h]hContext}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj-ubhG. Questo dovrebbe informare sulla possibilità che una funzione dorma (}(hj-hhhNhNubjL)}(h*sleep*h]hsleep}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj-ubhL) o che possa essere chiamata in un contesto d’interruzione, così come i }(hj-hhhNhNubjL)}(h*lock*h]hlock}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj-ubhG che prende, rilascia e che si aspetta che vengano presi dal chiamante.}(hj-hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhKhjhhubh)}(hEsempi::h]hEsempi:}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjhhubj)}(hXj* Context: Any context. * Context: Any context. Takes and releases the RCU lock. * Context: Any context. Expects to be held by caller. * Context: Process context. May sleep if @gfp flags permit. * Context: Process context. Takes and releases . * Context: Softirq or process context. Takes and releases , BH-safe. * Context: Interrupt context.h]hXj* Context: Any context. * Context: Any context. Takes and releases the RCU lock. * Context: Any context. Expects to be held by caller. * Context: Process context. May sleep if @gfp flags permit. * Context: Process context. Takes and releases . * Context: Softirq or process context. Takes and releases , BH-safe. * Context: Interrupt context.}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhKhjhhubeh}(h]contesto-delle-funzioniah ]h"]contesto delle funzioniah$]h&]uh1j0hjhhhjhKubj1)}(hhh](j6)}(hValore di ritornoh]hValore di ritorno}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjhhhjhKubh)}(hZIl valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome ``Return``.h](hQIl valore di ritorno, se c’è, viene descritto in una sezione dedicata di nome }(hjhhhNhNubj)}(h ``Return``h]hReturn}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhKhjhhubh)}(hX[#) La descrizione multiriga non riconosce il termine d'una riga, per cui se provate a formattare bene il vostro testo come nel seguente esempio:: * Return: * %0 - OK * %-EINVAL - invalid argument * %-ENOMEM - out of memory le righe verranno unite e il risultato sarà:: Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory Quindi, se volete che le righe vengano effettivamente generate, dovete utilizzare una lista ReST, ad esempio:: * Return: * * %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 di una nuova sezione, e probabilmente non produrrà gli effetti desiderati.h]henumerated_list)}(hhh](h list_item)}(hXMLa descrizione multiriga non riconosce il termine d'una riga, per cui se provate a formattare bene il vostro testo come nel seguente esempio:: * Return: * %0 - OK * %-EINVAL - invalid argument * %-ENOMEM - out of memory le righe verranno unite e il risultato sarà:: Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory Quindi, se volete che le righe vengano effettivamente generate, dovete utilizzare una lista ReST, ad esempio:: * Return: * * %0 - OK to runtime suspend the device * * %-EBUSY - Device should not be runtime suspended h](h)}(hLa descrizione multiriga non riconosce il termine d'una riga, per cui se provate a formattare bene il vostro testo come nel seguente esempio::h]hLa descrizione multiriga non riconosce il termine d’una riga, per cui se provate a formattare bene il vostro testo come nel seguente esempio:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubj)}(hL* Return: * %0 - OK * %-EINVAL - invalid argument * %-ENOMEM - out of memoryh]hL* Return: * %0 - OK * %-EINVAL - invalid argument * %-ENOMEM - out of memory}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhKhjubh)}(h.le righe verranno unite e il risultato sarà::h]h-le righe verranno unite e il risultato sarà:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubj)}(hAReturn: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memoryh]hAReturn: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhKhjubh)}(hnQuindi, se volete che le righe vengano effettivamente generate, dovete utilizzare una lista ReST, ad esempio::h]hmQuindi, se volete che le righe vengano effettivamente generate, dovete utilizzare una lista ReST, ad esempio:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjubj)}(hy* Return: * * %0 - OK to runtime suspend the device * * %-EBUSY - Device should not be runtime suspendedh]hy* Return: * * %0 - OK to runtime suspend the device * * %-EBUSY - Device should not be runtime suspended}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhKhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hSe 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 di una nuova sezione, e probabilmente non produrrà gli effetti desiderati.h]h)}(hSe 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 di una nuova sezione, e probabilmente non produrrà gli effetti desiderati.h]hSe 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 di una nuova sezione, e probabilmente non produrrà gli effetti desiderati.}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhj/ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix)uh1jhjubah}(h]h ]h"]h$]h&]uh1hhjhhhNhNubeh}(h]valore-di-ritornoah ]h"]valore di ritornoah$]h&]uh1j0hjhhhjhKubeh}(h]documentare-le-funzioniah ]h"]documentare le funzioniah$]h&]uh1j0hj2hhhjhK[ubj1)}(hhh](j6)}(h-Documentare strutture, unioni ed enumerazionih]h-Documentare strutture, unioni ed enumerazioni}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjhhhhjhKubh)}(hPGeneralmente il formato di un commento kernel-doc per struct, union ed enum è::h]hOGeneralmente il formato di un commento kernel-doc per struct, union ed enum è:}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhjhhhubj)}(h/** * struct struct_name - Brief description. * @member1: Description of member1. * @member2: Description of member2. * One can provide multiple line descriptions * for members. * * Description of the structure. */h]h/** * struct struct_name - Brief description. * @member1: Description of member1. * @member2: Description of member2. * One can provide multiple line descriptions * for members. * * Description of the structure. */}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhKhjhhhubh)}(hNell'esempio qui sopra, potete sostituire ``struct`` con ``union`` o ``enum`` per descrivere unioni ed enumerati. ``member`` viene usato per indicare i membri di strutture ed unioni, ma anche i valori di un tipo enumerato.h](h,Nell’esempio qui sopra, potete sostituire }(hjhhhNhNubj)}(h ``struct``h]hstruct}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh con }(hjhhhNhNubj)}(h ``union``h]hunion}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh o }(hjhhhNhNubj)}(h``enum``h]henum}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh% per descrivere unioni ed enumerati. }(hjhhhNhNubj)}(h ``member``h]hmember}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhb viene usato per indicare i membri di strutture ed unioni, ma anche i valori di un tipo enumerato.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhKhjhhhubh)}(hLa descrizione introduttiva (*brief description*) che segue il nome della funzione può continuare su righe successive e termina con la descrizione di un argomento, una linea di commento vuota, oppure la fine del commento.h](hLa descrizione introduttiva (}(hjhhhNhNubjL)}(h*brief description*h]hbrief description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh) che segue il nome della funzione può continuare su righe successive e termina con la descrizione di un argomento, una linea di commento vuota, oppure la fine del commento.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhKhjhhhubj1)}(hhh](j6)}(hMembrih]hMembri}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj hhhjhKubh)}(hI membri di strutture, unioni ed enumerati devo essere documentati come i parametri delle funzioni; seguono la descrizione introduttiva e possono estendersi su più righe.h]hI membri di strutture, unioni ed enumerati devo essere documentati come i parametri delle funzioni; seguono la descrizione introduttiva e possono estendersi su più righe.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhj hhubh)}(hAll'interno d'una struttura o d'un unione, potete utilizzare le etichette ``private:`` e ``public:``. I campi che sono nell'area ``private:`` non verranno inclusi nella documentazione finale.h](hPAll’interno d’una struttura o d’un unione, potete utilizzare le etichette }(hj*hhhNhNubj)}(h ``private:``h]hprivate:}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj*ubh e }(hj*hhhNhNubj)}(h ``public:``h]hpublic:}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj*ubh. I campi che sono nell’area }(hj*hhhNhNubj)}(h ``private:``h]hprivate:}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj*ubh2 non verranno inclusi nella documentazione finale.}(hj*hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhKhj hhubh)}(hLe etichette ``private:`` e ``public:`` devono essere messe subito dopo il marcatore di un commento ``/*``. Opzionalmente, possono includere commenti fra ``:`` e il marcatore di fine commento ``*/``.h](h Le etichette }(hjnhhhNhNubj)}(h ``private:``h]hprivate:}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjnubh e }(hjnhhhNhNubj)}(h ``public:``h]hpublic:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjnubh= devono essere messe subito dopo il marcatore di un commento }(hjnhhhNhNubj)}(h``/*``h]h/*}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjnubh0. Opzionalmente, possono includere commenti fra }(hjnhhhNhNubj)}(h``:``h]h:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjnubh! e il marcatore di fine commento }(hjnhhhNhNubj)}(h``*/``h]h*/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjnubh.}(hjnhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhKhj hhubh)}(h Esempio::h]hEsempio:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKhj hhubj)}(hX/** * struct my_struct - short description * @a: first member * @b: second member * @d: fourth member * * Longer description */ struct my_struct { int a; int b; /* private: internal use only */ int c; /* public: the next one is public */ int d; };h]hX/** * struct my_struct - short description * @a: first member * @b: second member * @d: fourth member * * Longer description */ struct my_struct { int a; int b; /* private: internal use only */ int c; /* public: the next one is public */ int d; };}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhKhj hhubeh}(h]membriah ]h"]membriah$]h&]uh1j0hjhhhhjhKubj1)}(hhh](j6)}(hStrutture ed unioni annidateh]hStrutture ed unioni annidate}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjhhhjhMubh)}(hCÈ possibile documentare strutture ed unioni annidate, ad esempio::h]hBÈ possibile documentare strutture ed unioni annidate, ad esempio:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhjhhubj)}(hX/** * struct nested_foobar - a struct with nested unions and structs * @memb1: first member of anonymous union/anonymous struct * @memb2: second member of anonymous union/anonymous struct * @memb3: third member of anonymous union/anonymous struct * @memb4: fourth member of anonymous union/anonymous struct * @bar: non-anonymous union * @bar.st1: struct st1 inside @bar * @bar.st2: struct st2 inside @bar * @bar.st1.memb1: first member of struct st1 on union bar * @bar.st1.memb2: second member of struct st1 on union bar * @bar.st2.memb1: first member of struct st2 on union bar * @bar.st2.memb2: second member of struct st2 on union bar */ struct nested_foobar { /* Anonymous union/struct*/ union { struct { int memb1; int memb2; } struct { void *memb3; int memb4; } } union { struct { int memb1; int memb2; } st1; struct { void *memb1; int memb2; } st2; } bar; };h]hX/** * struct nested_foobar - a struct with nested unions and structs * @memb1: first member of anonymous union/anonymous struct * @memb2: second member of anonymous union/anonymous struct * @memb3: third member of anonymous union/anonymous struct * @memb4: fourth member of anonymous union/anonymous struct * @bar: non-anonymous union * @bar.st1: struct st1 inside @bar * @bar.st2: struct st2 inside @bar * @bar.st1.memb1: first member of struct st1 on union bar * @bar.st1.memb2: second member of struct st1 on union bar * @bar.st2.memb1: first member of struct st2 on union bar * @bar.st2.memb2: second member of struct st2 on union bar */ struct nested_foobar { /* Anonymous union/struct*/ union { struct { int memb1; int memb2; } struct { void *memb3; int memb4; } } union { struct { int memb1; int memb2; } st1; struct { void *memb1; int memb2; } st2; } bar; };}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhMhjhhubh)}(hX#) Quando documentate una struttura od unione annidata, ad esempio di nome ``foo``, il suo campo ``bar`` dev'essere documentato usando ``@foo.bar:`` #) Quando la struttura od unione annidata è anonima, il suo campo ``bar`` dev'essere documentato usando ``@bar:``h]j)}(hhh](j)}(hQuando documentate una struttura od unione annidata, ad esempio di nome ``foo``, il suo campo ``bar`` dev'essere documentato usando ``@foo.bar:``h]h)}(hQuando documentate una struttura od unione annidata, ad esempio di nome ``foo``, il suo campo ``bar`` dev'essere documentato usando ``@foo.bar:``h](hHQuando documentate una struttura od unione annidata, ad esempio di nome }(hj2hhhNhNubj)}(h``foo``h]hfoo}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj2ubh, il suo campo }(hj2hhhNhNubj)}(h``bar``h]hbar}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj2ubh! dev’essere documentato usando }(hj2hhhNhNubj)}(h ``@foo.bar:``h]h @foo.bar:}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj2ubeh}(h]h ]h"]h$]h&]uh1hhjhM0hj.ubah}(h]h ]h"]h$]h&]uh1jhj+ubj)}(hoQuando la struttura od unione annidata è anonima, il suo campo ``bar`` dev'essere documentato usando ``@bar:``h]h)}(hoQuando la struttura od unione annidata è anonima, il suo campo ``bar`` dev'essere documentato usando ``@bar:``h](h@Quando la struttura od unione annidata è anonima, il suo campo }(hj|hhhNhNubj)}(h``bar``h]hbar}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj|ubh! dev’essere documentato usando }(hj|hhhNhNubj)}(h ``@bar:``h]h@bar:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj|ubeh}(h]h ]h"]h$]h&]uh1hhjhM3hjxubah}(h]h ]h"]h$]h&]uh1jhj+ubeh}(h]h ]h"]h$]h&]jMjNjOhjPjQuh1jhj'ubah}(h]h ]h"]h$]h&]uh1hhjhhhNhNubeh}(h]strutture-ed-unioni-annidateah ]h"]strutture ed unioni annidateah$]h&]uh1j0hjhhhhjhMubj1)}(hhh](j6)}(h2Commenti in linea per la documentazione dei membrih]h2Commenti in linea per la documentazione dei membri}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjhhhjhM7ubh)}(hI membri d'una struttura possono essere documentati in linea all'interno della definizione stessa. Ci sono due stili: una singola riga di commento che inizia con ``/**`` e finisce con ``*/``; commenti multi riga come qualsiasi altro commento kernel-doc::h](hI membri d’una struttura possono essere documentati in linea all’interno della definizione stessa. Ci sono due stili: una singola riga di commento che inizia con }(hjhhhNhNubj)}(h``/**``h]h/**}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh e finisce con }(hjhhhNhNubj)}(h``*/``h]h*/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh?; commenti multi riga come qualsiasi altro commento kernel-doc:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhM9hjhhubj)}(hX}/** * struct foo - Brief description. * @foo: The Foo member. */ struct foo { int foo; /** * @bar: The Bar member. */ int bar; /** * @baz: The Baz member. * * Here, the member description may contain several paragraphs. */ int baz; union { /** @foobar: Single line description. */ int foobar; }; /** @bar2: Description for struct @bar2 inside @foo */ struct { /** * @bar2.barbar: Description for @barbar inside @foo.bar2 */ int barbar; } bar2; };h]hX}/** * struct foo - Brief description. * @foo: The Foo member. */ struct foo { int foo; /** * @bar: The Bar member. */ int bar; /** * @baz: The Baz member. * * Here, the member description may contain several paragraphs. */ int baz; union { /** @foobar: Single line description. */ int foobar; }; /** @bar2: Description for struct @bar2 inside @foo */ struct { /** * @bar2.barbar: Description for @barbar inside @foo.bar2 */ int barbar; } bar2; };}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhM>hjhhubeh}(h]2commenti-in-linea-per-la-documentazione-dei-membriah ]h"]2commenti in linea per la documentazione dei membriah$]h&]uh1j0hjhhhhjhM7ubeh}(h],documentare-strutture-unioni-ed-enumerazioniah ]h"]-documentare strutture, unioni ed enumerazioniah$]h&]uh1j0hj2hhhjhKubj1)}(hhh](j6)}(hDocumentazione dei tipi di datoh]hDocumentazione dei tipi di dato}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj%hhhjhM]ubh)}(hNGeneralmente il formato di un commento kernel-doc per typedef è il seguente::h]hMGeneralmente il formato di un commento kernel-doc per typedef è il seguente:}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhM^hj%hhubj)}(hP/** * typedef type_name - Brief description. * * Description of the type. */h]hP/** * typedef type_name - Brief description. * * Description of the type. */}hjDsbah}(h]h ]h"]h$]h&]jjuh1jhjhMahj%hhubh)}(hKAnche i tipi di dato per prototipi di funzione possono essere documentati::h]hJAnche i tipi di dato per prototipi di funzione possono essere documentati:}(hjRhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMghj%hhubj)}(hX/** * typedef type_name - Brief description. * @arg1: description of arg1 * @arg2: description of arg2 * * Description of the type. * * Context: Locking context. * Return: Meaning of the return value. */ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);h]hX/** * typedef type_name - Brief description. * @arg1: description of arg1 * @arg2: description of arg2 * * Description of the type. * * Context: Locking context. * Return: Meaning of the return value. */ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);}hj`sbah}(h]h ]h"]h$]h&]jjuh1jhjhMihj%hhubeh}(h]documentazione-dei-tipi-di-datoah ]h"]documentazione dei tipi di datoah$]h&]uh1j0hj2hhhjhM]ubj1)}(hhh](j6)}(h(Documentazione di macro simili a oggettih]h(Documentazione di macro simili a oggetti}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjvhhhjhMvubh)}(hLe 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.h]hLe 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMxhjvhhubh)}(hLe 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.h](h9Le macro simili a funzioni sono gestite come funzioni da }(hjhhhNhNubj)}(h``scripts/kernel-doc``h]hscripts/kernel-doc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhc. Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un elenco di parametri.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhM}hjvhhubh)}(hQIl formato generale di un commento kernel-doc per una macro simile a oggetti è::h]hPIl formato generale di un commento kernel-doc per una macro simile a oggetti è:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhjvhhubj)}(hS/** * define object_name - Brief description. * * Description of the object. */h]hS/** * define object_name - Brief description. * * Description of the object. */}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhMhjvhhubh)}(h Esempio::h]hEsempio:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhjvhhubj)}(hX/** * 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 4095h]hX/** * 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}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhMhjvhhubh)}(h Esempio::h]hEsempio:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhjvhhubj)}(hX|/** * 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_fbh]hX|/** * 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}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhMhjvhhubeh}(h](documentazione-di-macro-simili-a-oggettiah ]h"](documentazione di macro simili a oggettiah$]h&]uh1j0hj2hhhjhMvubj1)}(hhh](j6)}(hMarcatori e riferimentih]hMarcatori e riferimenti}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj hhhjhMubh)}(hAll'interno dei commenti di tipo kernel-doc vengono riconosciuti i seguenti *pattern* che vengono convertiti in marcatori reStructuredText ed in riferimenti del `dominio Sphinx per il C`_.h](hNAll’interno dei commenti di tipo kernel-doc vengono riconosciuti i seguenti }(hj" hhhNhNubjL)}(h *pattern*h]hpattern}(hj* hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj" ubhL che vengono convertiti in marcatori reStructuredText ed in riferimenti del }(hj" hhhNhNubjt)}(h`dominio Sphinx per il C`_h]hdominio Sphinx per il C}(hj< hhhNhNubah}(h]h ]h"]h$]h&]namedominio Sphinx per il Cjjuh1jshj" jKubh.}(hj" hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhMhj hhubh attention)}(hzQuesti sono riconosciuti **solo** all'interno di commenti kernel-doc, e **non** all'interno di documenti reStructuredText.h]h)}(hzQuesti sono riconosciuti **solo** all'interno di commenti kernel-doc, e **non** all'interno di documenti reStructuredText.h](hQuesti sono riconosciuti }(hj\ hhhNhNubhstrong)}(h**solo**h]hsolo}(hjf hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hj\ ubh) all’interno di commenti kernel-doc, e }(hj\ hhhNhNubje )}(h**non**h]hnon}(hjx hhhNhNubah}(h]h ]h"]h$]h&]uh1jd hj\ ubh- all’interno di documenti reStructuredText.}(hj\ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhMhjX ubah}(h]h ]h"]h$]h&]uh1jV hj hhhjhNubhdefinition_list)}(hhh](hdefinition_list_item)}(h,``funcname()`` Riferimento ad una funzione. h](hterm)}(h``funcname()``h]j)}(hj h]h funcname()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1j hjhMhj ubh definition)}(hhh]h)}(hRiferimento ad una funzione.h]hRiferimento ad una funzione.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhj ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hjhMhj ubj )}(h^``@parameter`` Nome di un parametro di una funzione (nessun riferimento, solo formattazione). h](j )}(h``@parameter``h]j)}(hj h]h @parameter}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1j hjhMhj ubj )}(hhh]h)}(hNNome di un parametro di una funzione (nessun riferimento, solo formattazione).h]hNNome di un parametro di una funzione (nessun riferimento, solo formattazione).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhj ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hjhMhj hhubj )}(hL``%CONST`` Il nome di una costante (nessun riferimento, solo formattazione) h](j )}(h ``%CONST``h]j)}(hj h]h%CONST}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1j hjhMhj ubj )}(hhh]h)}(h@Il nome di una costante (nessun riferimento, solo formattazione)h]h@Il nome di una costante (nessun riferimento, solo formattazione)}(hj/ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhj, ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hjhMhj hhubj )}(hX````literal```` Un blocco di testo che deve essere riportato così com'è. La rappresentazione finale utilizzerà caratteri a ``spaziatura fissa``. Questo è utile se dovete utilizzare caratteri speciali che altrimenti potrebbero assumere un significato diverso in kernel-doc o in reStructuredText Questo è particolarmente utile se dovete scrivere qualcosa come ``%ph`` all'interno della descrizione di una funzione. h](j )}(h````literal````h]j)}(hjO h]h ``literal``}(hjQ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjM ubah}(h]h ]h"]h$]h&]uh1j hjhMhjI ubj )}(hhh](h)}(hUn blocco di testo che deve essere riportato così com'è. La rappresentazione finale utilizzerà caratteri a ``spaziatura fissa``.h](hpUn blocco di testo che deve essere riportato così com’è. La rappresentazione finale utilizzerà caratteri a }(hjg hhhNhNubj)}(h``spaziatura fissa``h]hspaziatura fissa}(hjo hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjg ubh.}(hjg hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhMhjd ubh)}(hQuesto è utile se dovete utilizzare caratteri speciali che altrimenti potrebbero assumere un significato diverso in kernel-doc o in reStructuredTexth]hQuesto è utile se dovete utilizzare caratteri speciali che altrimenti potrebbero assumere un significato diverso in kernel-doc o in reStructuredText}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhjd ubh)}(hwQuesto è particolarmente utile se dovete scrivere qualcosa come ``%ph`` all'interno della descrizione di una funzione.h](hAQuesto è particolarmente utile se dovete scrivere qualcosa come }(hj hhhNhNubj)}(h``%ph``h]h%ph}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh1 all’interno della descrizione di una funzione.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhMhjd ubeh}(h]h ]h"]h$]h&]uh1j hjI ubeh}(h]h ]h"]h$]h&]uh1j hjhMhj hhubj )}(hZ``$ENVVAR`` Il nome di una variabile d'ambiente (nessun riferimento, solo formattazione). h](j )}(h ``$ENVVAR``h]j)}(hj h]h$ENVVAR}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1j hjhMhj ubj )}(hhh]h)}(hMIl nome di una variabile d'ambiente (nessun riferimento, solo formattazione).h]hOIl nome di una variabile d’ambiente (nessun riferimento, solo formattazione).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhj ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hjhMhj hhubj )}(h/``&struct name`` Riferimento ad una struttura. h](j )}(h``&struct name``h]j)}(hj h]h &struct name}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1j hjhMhj ubj )}(hhh]h)}(hRiferimento ad una struttura.h]hRiferimento ad una struttura.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhj ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hjhMhj hhubj )}(h/``&enum name`` Riferimento ad un'enumerazione. h](j )}(h``&enum name``h]j)}(hj7 h]h &enum name}(hj9 hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj5 ubah}(h]h ]h"]h$]h&]uh1j hjhMhj1 ubj )}(hhh]h)}(hRiferimento ad un'enumerazione.h]h!Riferimento ad un’enumerazione.}(hjO hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhjL ubah}(h]h ]h"]h$]h&]uh1j hj1 ubeh}(h]h ]h"]h$]h&]uh1j hjhMhj hhubj )}(h2``&typedef name`` Riferimento ad un tipo di dato. h](j )}(h``&typedef name``h]j)}(hjo h]h &typedef name}(hjq hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjm ubah}(h]h ]h"]h$]h&]uh1j hjhMhji ubj )}(hhh]h)}(hRiferimento ad un tipo di dato.h]hRiferimento ad un tipo di dato.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhj ubah}(h]h ]h"]h$]h&]uh1j hji ubeh}(h]h ]h"]h$]h&]uh1j hjhMhj hhubj )}(h``&struct_name->member`` or ``&struct_name.member`` Riferimento ad un membro di una struttura o di un'unione. Il riferimento sarà la struttura o l'unione, non il memembro. h](j )}(h3``&struct_name->member`` or ``&struct_name.member``h](j)}(h``&struct_name->member``h]h&struct_name->member}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh or }(hj hhhNhNubj)}(h``&struct_name.member``h]h&struct_name.member}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j hjhMhj ubj )}(hhh]h)}(hxRiferimento ad un membro di una struttura o di un'unione. Il riferimento sarà la struttura o l'unione, non il memembro.h]h|Riferimento ad un membro di una struttura o di un’unione. Il riferimento sarà la struttura o l’unione, non il memembro.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhj ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hjhMhj hhubj )}(h``&name`` Un generico riferimento ad un tipo. Usate, preferibilmente, il riferimento completo come descritto sopra. Questo è dedicato ai commenti obsoleti. h](j )}(h ``&name``h]j)}(hj h]h&name}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1j hjhMhj ubj )}(hhh]h)}(hUn generico riferimento ad un tipo. Usate, preferibilmente, il riferimento completo come descritto sopra. Questo è dedicato ai commenti obsoleti.h]hUn generico riferimento ad un tipo. Usate, preferibilmente, il riferimento completo come descritto sopra. Questo è dedicato ai commenti obsoleti.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhj ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hjhMhj hhubeh}(h]h ]h"]h$]h&]uh1j hj hhhjhNubj1)}(hhh](j6)}(h#Riferimenti usando reStructuredTexth]h#Riferimenti usando reStructuredText}(hj- hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj* hhhjhMubh)}(hXNei 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::h](hNei 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 }(hj; hhhNhNubj)}(h``()``h]h()}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj; ubh , e scrivere }(hj; hhhNhNubj)}(h ``struct``h]hstruct}(hjU hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj; ubh, }(hj; hhhNhNubj)}(h ``union``h]hunion}(hjg hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj; ubh, }hj; sbj)}(h``enum``h]henum}(hjy hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj; ubh, o }(hj; hhhNhNubj)}(h ``typedef``h]htypedef}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj; ubh prima di un tipo. Per esempio:}(hj; hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhMhj* hhubj)}(hGSee foo() See struct foo. See union bar. See enum baz. See typedef meh.h]hGSee foo() See struct foo. See union bar. See enum baz. See typedef meh.}hj sbah}(h]h ]h"]h$]h&]jjuh1jhjhMhj* hhubh)}(h\Tuttavia, la personalizzazione dei collegamenti è possibile solo con la seguente sintassi::h]h[Tuttavia, la personalizzazione dei collegamenti è possibile solo con la seguente sintassi:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhj* hhubj)}(hqSee :c:func:`my custom link text for function foo `. See :c:type:`my custom link text for struct bar `.h]hqSee :c:func:`my custom link text for function foo `. See :c:type:`my custom link text for struct bar `.}hj sbah}(h]h ]h"]h$]h&]jjuh1jhjhMhj* hhubeh}(h]#riferimenti-usando-restructuredtextah ]h"]#riferimenti usando restructuredtextah$]h&]uh1j0hj hhhjhMubeh}(h]marcatori-e-riferimentiah ]h"]marcatori e riferimentiah$]h&]uh1j0hj2hhhjhMubj1)}(hhh](j6)}(h(Commenti per una documentazione generaleh]h(Commenti per una documentazione generale}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj hhhjhMubh)}(hXdAl fine d'avere il codice ed i commenti nello stesso file, potete includere dei blocchi di documentazione kernel-doc con un formato libero invece che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi di dato. Per esempio, questo tipo di commento potrebbe essere usato per la spiegazione delle operazioni di un driver o di una libreriah]hXfAl fine d’avere il codice ed i commenti nello stesso file, potete includere dei blocchi di documentazione kernel-doc con un formato libero invece che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi di dato. Per esempio, questo tipo di commento potrebbe essere usato per la spiegazione delle operazioni di un driver o di una libreria}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhj hhubh)}(hWQuesto s'ottiene utilizzando la parola chiave ``DOC:`` a cui viene associato un titolo.h](h0Questo s’ottiene utilizzando la parola chiave }(hj hhhNhNubj)}(h``DOC:``h]hDOC:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh! a cui viene associato un titolo.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhMhj hhubh)}(hWGeneralmente il formato di un commento generico o di visione d'insieme è il seguente::h]hXGeneralmente il formato di un commento generico o di visione d’insieme è il seguente:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhj hhubj)}(hX7/** * DOC: Theory of Operation * * The whizbang foobar is a dilly of a gizmo. It can do whatever you * want it to do, at any time. It reads your mind. Here's how it works. * * foo bar splat * * The only drawback to this gizmo is that is can sometimes damage * hardware, software, or its subject(s). */h]hX7/** * DOC: Theory of Operation * * The whizbang foobar is a dilly of a gizmo. It can do whatever you * want it to do, at any time. It reads your mind. Here's how it works. * * foo bar splat * * The only drawback to this gizmo is that is can sometimes damage * hardware, software, or its subject(s). */}hj* sbah}(h]h ]h"]h$]h&]jjuh1jhjhMhj hhubh)}(hIl 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.h](hIl titolo che segue }(hj8 hhhNhNubj)}(h``DOC:``h]hDOC:}(hj@ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj8 ubh 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.}(hj8 hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhMhj hhubeh}(h](commenti-per-una-documentazione-generaleah ]h"](commenti per una documentazione generaleah$]h&]uh1j0hj2hhhjhMubeh}(h](!scrivere-i-commenti-in-kernel-docj/eh ]h"](!scrivere i commenti in kernel-doc it_kernel_doceh$]h&]uh1j0hhhhhjhK expect_referenced_by_name}jf j$sexpect_referenced_by_id}j/j$subj1)}(hhh](j6)}(h'Includere i commenti di tipo kernel-doch]h'Includere i commenti di tipo kernel-doc}(hjp hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjm hhhjhM ubh)}(hI commenti di documentazione possono essere inclusi in un qualsiasi documento di tipo reStructuredText mediante l'apposita direttiva nell'estensione kernel-doc per Sphinx.h]hI commenti di documentazione possono essere inclusi in un qualsiasi documento di tipo reStructuredText mediante l’apposita direttiva nell’estensione kernel-doc per Sphinx.}(hj~ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhM hjm hhubh)}(h*Le direttive kernel-doc sono nel formato::h]h)Le direttive kernel-doc sono nel formato:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhjm hhubj)}(h".. kernel-doc:: source :option:h]h".. kernel-doc:: source :option:}hj sbah}(h]h G]h"]h$]h&]jjuh1jhjhMhjm hhubh)}(hIl campo *source* è il percorso ad un file sorgente, relativo alla cartella principale dei sorgenti del kernel. La direttiva supporta le seguenti opzioni:h](h Il campo }(hj hhhNhNubjL)}(h*source*h]hsource}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj ubh è il percorso ad un file sorgente, relativo alla cartella principale dei sorgenti del kernel. La direttiva supporta le seguenti opzioni:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhMhjm hhubj )}(hhh](j )}(hXTexport: *[source-pattern ...]* Include la documentazione per tutte le funzioni presenti nel file sorgente (*source*) che sono state esportate utilizzando ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` in *source* o in qualsiasi altro *source-pattern* specificato. Il campo *source-patter* è utile quando i commenti kernel-doc sono stati scritti nei file d'intestazione, mentre ``EXPORT_SYMBOL`` e ``EXPORT_SYMBOL_GPL`` si trovano vicino alla definizione delle funzioni. Esempi:: .. kernel-doc:: lib/bitmap.c :export: .. kernel-doc:: include/net/mac80211.h :export: net/mac80211/*.c h](j )}(hexport: *[source-pattern ...]*h](hexport: }(hj hhhNhNubjL)}(h*[source-pattern ...]*h]h[source-pattern ...]}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj ubeh}(h]h ]h"]h$]h&]uh1j hjhM'hj ubj )}(hhh](h)}(hInclude la documentazione per tutte le funzioni presenti nel file sorgente (*source*) che sono state esportate utilizzando ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` in *source* o in qualsiasi altro *source-pattern* specificato.h](hLInclude la documentazione per tutte le funzioni presenti nel file sorgente (}(hj hhhNhNubjL)}(h*source*h]hsource}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj ubh') che sono state esportate utilizzando }(hj hhhNhNubj)}(h``EXPORT_SYMBOL``h]h EXPORT_SYMBOL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh o }(hj hhhNhNubj)}(h``EXPORT_SYMBOL_GPL``h]hEXPORT_SYMBOL_GPL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh in }(hj hhhNhNubjL)}(h*source*h]hsource}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj ubh o in qualsiasi altro }(hj hhhNhNubjL)}(h*source-pattern*h]hsource-pattern}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj ubh specificato.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhMhj ubh)}(hIl campo *source-patter* è utile quando i commenti kernel-doc sono stati scritti nei file d'intestazione, mentre ``EXPORT_SYMBOL`` e ``EXPORT_SYMBOL_GPL`` si trovano vicino alla definizione delle funzioni.h](h Il campo }(hjVhhhNhNubjL)}(h*source-patter*h]h source-patter}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjVubh\ è utile quando i commenti kernel-doc sono stati scritti nei file d’intestazione, mentre }(hjVhhhNhNubj)}(h``EXPORT_SYMBOL``h]h EXPORT_SYMBOL}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1jhjVubh e }(hjVhhhNhNubj)}(h``EXPORT_SYMBOL_GPL``h]hEXPORT_SYMBOL_GPL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjVubh3 si trovano vicino alla definizione delle funzioni.}(hjVhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhMhj ubh)}(hEsempi::h]hEsempi:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhM!hj ubj)}(hm.. kernel-doc:: lib/bitmap.c :export: .. kernel-doc:: include/net/mac80211.h :export: net/mac80211/*.ch]hm.. kernel-doc:: lib/bitmap.c :export: .. kernel-doc:: include/net/mac80211.h :export: net/mac80211/*.c}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhM#hj ubeh}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1j hjhM'hj ubj )}(hXninternal: *[source-pattern ...]* Include la documentazione per tutte le funzioni ed i tipi presenti nel file sorgente (*source*) che **non** sono stati esportati utilizzando ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` né in *source* né in qualsiasi altro *source-pattern* specificato. Esempio:: .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :internal: h](j )}(h internal: *[source-pattern ...]*h](h internal: }(hjhhhNhNubjL)}(h*[source-pattern ...]*h]h[source-pattern ...]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j hjhM2hjubj )}(hhh](h)}(hInclude la documentazione per tutte le funzioni ed i tipi presenti nel file sorgente (*source*) che **non** sono stati esportati utilizzando ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` né in *source* né in qualsiasi altro *source-pattern* specificato.h](hVInclude la documentazione per tutte le funzioni ed i tipi presenti nel file sorgente (}(hjhhhNhNubjL)}(h*source*h]hsource}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh) che }(hjhhhNhNubje )}(h**non**h]hnon}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jd hjubh" sono stati esportati utilizzando }(hjhhhNhNubj)}(h``EXPORT_SYMBOL``h]h EXPORT_SYMBOL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh o }(hjhhhNhNubj)}(h``EXPORT_SYMBOL_GPL``h]hEXPORT_SYMBOL_GPL}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh né in }(hjhhhNhNubjL)}(h*source*h]hsource}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh né in qualsiasi altro }(hjhhhNhNubjL)}(h*source-pattern*h]hsource-pattern}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh specificato.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhM*hjubh)}(h Esempio::h]hEsempio:}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhM/hjubj)}(h@.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :internal:h]h@.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :internal:}hjmsbah}(h]h ]h"]h$]h&]jjuh1jhjhM1hjubeh}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1j hjhM2hj hhubj )}(hXidentifiers: *[ 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: h](j )}(h#identifiers: *[ function/type ...]*h](h identifiers: }(hjhhhNhNubjL)}(h*[ function/type ...]*h]h[ function/type ...]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j hjhM?hjubj )}(hhh](h)}(hInclude 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*.h](h#Include la documentazione per ogni }(hjhhhNhNubjL)}(h *function*h]hfunction}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh e }(hjhhhNhNubjL)}(h*type*h]htype}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh in }(hjhhhNhNubjL)}(h*source*h]hsource}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubhz. Se non vengono esplicitamente specificate le funzioni da includere, allora verranno incluse tutte quelle disponibili in }(hjhhhNhNubjL)}(h*source*h]hsource}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhM5hjubh)}(hEsempi::h]hEsempi:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhM9hjubj)}(h.. kernel-doc:: lib/bitmap.c :identifiers: bitmap_parselist bitmap_parselist_user .. kernel-doc:: lib/idr.c :identifiers:h]h.. kernel-doc:: lib/bitmap.c :identifiers: bitmap_parselist bitmap_parselist_user .. kernel-doc:: lib/idr.c :identifiers:}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhM;hjubeh}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1j hjhM?hj hhubj )}(hbfunctions: *[ function ...]* Questo è uno pseudonimo, deprecato, per la direttiva 'identifiers'. h](j )}(hfunctions: *[ function ...]*h](h functions: }(hj,hhhNhNubjL)}(h*[ function ...]*h]h[ function ...]}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj,ubeh}(h]h ]h"]h$]h&]uh1j hjhMBhj(ubj )}(hhh]h)}(hDQuesto è uno pseudonimo, deprecato, per la direttiva 'identifiers'.h]hHQuesto è uno pseudonimo, deprecato, per la direttiva ‘identifiers’.}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMBhjHubah}(h]h ]h"]h$]h&]uh1j hj(ubeh}(h]h ]h"]h$]h&]uh1j hjhMBhj hhubj )}(hX doc: *title* Include la documentazione del paragrafo ``DOC:`` identificato dal titolo (*title*) all'interno del file sorgente (*source*). Gli spazi in *title* sono permessi; non virgolettate *title*. Il campo *title* è utilizzato per identificare un paragrafo e per questo non viene incluso nella documentazione finale. Verificate d'avere l'intestazione appropriata nei documenti reStructuredText. Esempio:: .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :doc: High Definition Audio over HDMI and Display Port h](j )}(h doc: *title*h](hdoc: }(hjihhhNhNubjL)}(h*title*h]htitle}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjiubeh}(h]h ]h"]h$]h&]uh1j hjhMOhjeubj )}(hhh](h)}(hXInclude la documentazione del paragrafo ``DOC:`` identificato dal titolo (*title*) all'interno del file sorgente (*source*). Gli spazi in *title* sono permessi; non virgolettate *title*. Il campo *title* è utilizzato per identificare un paragrafo e per questo non viene incluso nella documentazione finale. Verificate d'avere l'intestazione appropriata nei documenti reStructuredText.h](h(Include la documentazione del paragrafo }(hjhhhNhNubj)}(h``DOC:``h]hDOC:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh identificato dal titolo (}(hjhhhNhNubjL)}(h*title*h]htitle}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh#) all’interno del file sorgente (}(hjhhhNhNubjL)}(h*source*h]hsource}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh). Gli spazi in }(hjhhhNhNubjL)}(h*title*h]htitle}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh! sono permessi; non virgolettate }(hjhhhNhNubjL)}(h*title*h]htitle}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh . Il campo }(hjhhhNhNubjL)}(h*title*h]htitle}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh è utilizzato per identificare un paragrafo e per questo non viene incluso nella documentazione finale. Verificate d’avere l’intestazione appropriata nei documenti reStructuredText.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhMEhjubh)}(h Esempio::h]hEsempio:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMLhjubj)}(hl.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :doc: High Definition Audio over HDMI and Display Porth]hl.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :doc: High Definition Audio over HDMI and Display Port}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhMNhjubeh}(h]h ]h"]h$]h&]uh1j hjeubeh}(h]h ]h"]h$]h&]uh1j hjhMOhj hhubeh}(h]h ]h"]h$]h&]uh1j hjm hhhjhNubh)}(hSenza alcuna opzione, la direttiva kernel-doc include tutti i commenti di documentazione presenti nel file sorgente (*source*).h](huSenza alcuna opzione, la direttiva kernel-doc include tutti i commenti di documentazione presenti nel file sorgente (}(hj0hhhNhNubjL)}(h*source*h]hsource}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj0ubh).}(hj0hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhMQhjm hhubh)}(hL'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione dai file sorgenti.h](hRL’estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare in }(hjPhhhNhNubj)}(h%``Documentation/sphinx/kerneldoc.py``h]h!Documentation/sphinx/kerneldoc.py}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjPubh+. Internamente, viene utilizzato lo script }(hjPhhhNhNubj)}(h``scripts/kernel-doc``h]hscripts/kernel-doc}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjPubh= per estrarre i commenti di documentazione dai file sorgenti.}(hjPhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjhMThjm hhubj1)}(hhh](j6)}(h2Come utilizzare kernel-doc per generare pagine manh]h2Come utilizzare kernel-doc per generare pagine man}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjhhhjhMZubh)}(hwSe volete utilizzare kernel-doc solo per generare delle pagine man, potete farlo direttamente dai sorgenti del kernel::h]hvSe volete utilizzare kernel-doc solo per generare delle pagine man, potete farlo direttamente dai sorgenti del kernel:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhM\hjhhubj)}(hk$ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/manh]hk$ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man}hjsbah}(h]h ]h"]h$]h&]jjuh1jhjhM_hjhhubeh}(h]2come-utilizzare-kernel-doc-per-generare-pagine-manah ]h"]2come utilizzare kernel-doc per generare pagine manah$]h&]uh1j0hjm hhhjhMZubeh}(h]'includere-i-commenti-di-tipo-kernel-docah ]h"]'includere i commenti di tipo kernel-docah$]h&]uh1j0hhhhhjhM ubeh}(h]h ]h"]h$]h&]sourcejj5Commenti in kernel-docuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(j5N generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcej _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}dominio sphinx per il c](juj< esrefids}j/]j$asnameids}(jf j/je jb jjjjjejbjjjjj]jZj"jjjjjjjjsjpj j j j j j j] jZ jjjju nametypes}(jf je jjjejjj]j"jjjjsj j j j] jjuh}(j/j2jb j2jjjj]jbjjjejjjZjjjhjj jjjjjpj%j jvj j j j* jZ j jjm jju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages]hsystem_message)}(hhh]h)}(hhh]h3Hyperlink target "it-kernel-doc" is not referenced.}hjOsbah}(h]h ]h"]h$]h&]uh1hhjLubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcejlineKuh1jJuba transformerN include_log]9Documentation/translations/it_IT/doc-guide/kernel-doc.rst(NNNNta decorationNhhub.