137912da4SFederico Vaga.. include:: ../disclaimer-ita.rst 237912da4SFederico Vaga 337912da4SFederico Vaga.. note:: Per leggere la documentazione originale in inglese: 437912da4SFederico Vaga :ref:`Documentation/doc-guide/index.rst <doc_guide>` 537912da4SFederico Vaga 6*3760fe20SFederico Vaga.. title:: Commenti in kernel-doc 7*3760fe20SFederico Vaga 837912da4SFederico Vaga.. _it_kernel_doc: 937912da4SFederico Vaga 10da1d9cafSFederico Vaga================================= 1137912da4SFederico VagaScrivere i commenti in kernel-doc 1237912da4SFederico Vaga================================= 1337912da4SFederico Vaga 1437912da4SFederico VagaNei file sorgenti del kernel Linux potrete trovare commenti di documentazione 1537912da4SFederico Vagastrutturanti secondo il formato kernel-doc. Essi possono descrivere funzioni, 1637912da4SFederico Vagatipi di dati, e l'architettura del codice. 1737912da4SFederico Vaga 1837912da4SFederico Vaga.. note:: Il formato kernel-doc può sembrare simile a gtk-doc o Doxygen ma 1937912da4SFederico Vaga in realtà è molto differente per ragioni storiche. I sorgenti del kernel 2037912da4SFederico Vaga contengono decine di migliaia di commenti kernel-doc. Siete pregati 2137912da4SFederico Vaga d'attenervi allo stile qui descritto. 2237912da4SFederico Vaga 2337912da4SFederico VagaLa struttura kernel-doc è estratta a partire dai commenti; da questi viene 2437912da4SFederico Vagagenerato il `dominio Sphinx per il C`_ con un'adeguata descrizione per le 2537912da4SFederico Vagafunzioni ed i tipi di dato con i loro relativi collegamenti. Le descrizioni 2637912da4SFederico Vagavengono filtrare per cercare i riferimenti ed i marcatori. 2737912da4SFederico Vaga 2837912da4SFederico VagaVedere di seguito per maggiori dettagli. 2937912da4SFederico Vaga 3037912da4SFederico Vaga.. _`dominio Sphinx per il C`: http://www.sphinx-doc.org/en/stable/domains.html 3137912da4SFederico Vaga 3237912da4SFederico VagaTutte le funzioni esportate verso i moduli esterni utilizzando 3337912da4SFederico Vaga``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` dovrebbero avere un commento 3437912da4SFederico Vagakernel-doc. Quando l'intenzione è di utilizzarle nei moduli, anche le funzioni 3537912da4SFederico Vagae le strutture dati nei file d'intestazione dovrebbero avere dei commenti 3637912da4SFederico Vagakernel-doc. 3737912da4SFederico Vaga 3837912da4SFederico VagaÈ considerata una buona pratica quella di fornire una documentazione formattata 3937912da4SFederico Vagasecondo kernel-doc per le funzioni che sono visibili da altri file del kernel 4037912da4SFederico Vaga(ovvero, che non siano dichiarate utilizzando ``static``). Raccomandiamo, 4137912da4SFederico Vagainoltre, di fornire una documentazione kernel-doc anche per procedure private 4237912da4SFederico Vaga(ovvero, dichiarate "static") al fine di fornire una struttura più coerente 4337912da4SFederico Vagadei sorgenti. Quest'ultima raccomandazione ha una priorità più bassa ed è a 4437912da4SFederico Vagadiscrezione dal manutentore (MAINTAINER) del file sorgente. 4537912da4SFederico Vaga 4637912da4SFederico Vaga 4737912da4SFederico Vaga 4837912da4SFederico VagaSicuramente la documentazione formattata con kernel-doc è necessaria per 4937912da4SFederico Vagale funzioni che sono esportate verso i moduli esterni utilizzando 5037912da4SFederico Vaga``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL``. 5137912da4SFederico Vaga 5237912da4SFederico VagaCerchiamo anche di fornire una documentazione formattata secondo kernel-doc 5337912da4SFederico Vagaper le funzioni che sono visibili da altri file del kernel (ovvero, che non 5437912da4SFederico Vagasiano dichiarate utilizzando "static") 5537912da4SFederico Vaga 5637912da4SFederico VagaRaccomandiamo, inoltre, di fornire una documentazione formattata con kernel-doc 5737912da4SFederico Vagaanche per procedure private (ovvero, dichiarate "static") al fine di fornire 5837912da4SFederico Vagauna struttura più coerente dei sorgenti. Questa raccomandazione ha una priorità 5937912da4SFederico Vagapiù bassa ed è a discrezione dal manutentore (MAINTAINER) del file sorgente. 6037912da4SFederico Vaga 6137912da4SFederico VagaLe strutture dati visibili nei file di intestazione dovrebbero essere anch'esse 6237912da4SFederico Vagadocumentate utilizzando commenti formattati con kernel-doc. 6337912da4SFederico Vaga 6437912da4SFederico VagaCome formattare i commenti kernel-doc 6537912da4SFederico Vaga------------------------------------- 6637912da4SFederico Vaga 6737912da4SFederico VagaI commenti kernel-doc iniziano con il marcatore ``/**``. Il programma 6837912da4SFederico Vaga``kernel-doc`` estrarrà i commenti marchiati in questo modo. Il resto 6937912da4SFederico Vagadel commento è formattato come un normale commento multilinea, ovvero 7037912da4SFederico Vagacon un asterisco all'inizio d'ogni riga e che si conclude con ``*/`` 7137912da4SFederico Vagasu una riga separata. 7237912da4SFederico Vaga 7337912da4SFederico VagaI commenti kernel-doc di funzioni e tipi dovrebbero essere posizionati 7437912da4SFederico Vagaappena sopra la funzione od il tipo che descrivono. Questo allo scopo di 7537912da4SFederico Vagaaumentare la probabilità che chi cambia il codice si ricordi di aggiornare 7637912da4SFederico Vagaanche la documentazione. I commenti kernel-doc di tipo più generale possono 7737912da4SFederico Vagaessere posizionati ovunque nel file. 7837912da4SFederico Vaga 7937912da4SFederico VagaAl fine di verificare che i commenti siano formattati correttamente, potete 8037912da4SFederico Vagaeseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza 8137912da4SFederico Vagache questo produca alcuna documentazione. Per esempio:: 8237912da4SFederico Vaga 8337912da4SFederico Vaga scripts/kernel-doc -v -none drivers/foo/bar.c 8437912da4SFederico Vaga 8537912da4SFederico VagaIl formato della documentazione è verificato della procedura di generazione 8637912da4SFederico Vagadel kernel quando viene richiesto di effettuare dei controlli extra con GCC:: 8737912da4SFederico Vaga 8837912da4SFederico Vaga make W=n 8937912da4SFederico Vaga 9037912da4SFederico VagaDocumentare le funzioni 9137912da4SFederico Vaga------------------------ 9237912da4SFederico Vaga 9337912da4SFederico VagaGeneralmente il formato di un commento kernel-doc per funzioni e 9437912da4SFederico Vagamacro simil-funzioni è il seguente:: 9537912da4SFederico Vaga 9637912da4SFederico Vaga /** 9737912da4SFederico Vaga * function_name() - Brief description of function. 9837912da4SFederico Vaga * @arg1: Describe the first argument. 9937912da4SFederico Vaga * @arg2: Describe the second argument. 10037912da4SFederico Vaga * One can provide multiple line descriptions 10137912da4SFederico Vaga * for arguments. 10237912da4SFederico Vaga * 10337912da4SFederico Vaga * A longer description, with more discussion of the function function_name() 10437912da4SFederico Vaga * that might be useful to those using or modifying it. Begins with an 10537912da4SFederico Vaga * empty comment line, and may include additional embedded empty 10637912da4SFederico Vaga * comment lines. 10737912da4SFederico Vaga * 10837912da4SFederico Vaga * The longer description may have multiple paragraphs. 10937912da4SFederico Vaga * 11037912da4SFederico Vaga * Context: Describes whether the function can sleep, what locks it takes, 11137912da4SFederico Vaga * releases, or expects to be held. It can extend over multiple 11237912da4SFederico Vaga * lines. 113a929a42aSFederico Vaga * Return: Describe the return value of function_name. 11437912da4SFederico Vaga * 11537912da4SFederico Vaga * The return value description can also have multiple paragraphs, and should 11637912da4SFederico Vaga * be placed at the end of the comment block. 11737912da4SFederico Vaga */ 11837912da4SFederico Vaga 11937912da4SFederico VagaLa descrizione introduttiva (*brief description*) che segue il nome della 12037912da4SFederico Vagafunzione può continuare su righe successive e termina con la descrizione di 12137912da4SFederico Vagaun argomento, una linea di commento vuota, oppure la fine del commento. 12237912da4SFederico Vaga 12337912da4SFederico VagaParametri delle funzioni 12437912da4SFederico Vaga~~~~~~~~~~~~~~~~~~~~~~~~ 12537912da4SFederico Vaga 12637912da4SFederico VagaOgni argomento di una funzione dovrebbe essere descritto in ordine, subito 12737912da4SFederico Vagadopo la descrizione introduttiva. Non lasciare righe vuote né fra la 12837912da4SFederico Vagadescrizione introduttiva e quella degli argomenti, né fra gli argomenti. 12937912da4SFederico Vaga 13037912da4SFederico VagaOgni ``@argument:`` può estendersi su più righe. 13137912da4SFederico Vaga 13237912da4SFederico Vaga.. note:: 13337912da4SFederico Vaga 13437912da4SFederico Vaga Se la descrizione di ``@argument:`` si estende su più righe, 13537912da4SFederico Vaga la continuazione dovrebbe iniziare alla stessa colonna della riga 13637912da4SFederico Vaga precedente:: 13737912da4SFederico Vaga 13837912da4SFederico Vaga * @argument: some long description 13937912da4SFederico Vaga * that continues on next lines 14037912da4SFederico Vaga 14137912da4SFederico Vaga or:: 14237912da4SFederico Vaga 14337912da4SFederico Vaga * @argument: 14437912da4SFederico Vaga * some long description 14537912da4SFederico Vaga * that continues on next lines 14637912da4SFederico Vaga 14737912da4SFederico VagaSe una funzione ha un numero variabile di argomento, la sua descrizione 14837912da4SFederico Vagadovrebbe essere scritta con la notazione kernel-doc:: 14937912da4SFederico Vaga 15037912da4SFederico Vaga * @...: description 15137912da4SFederico Vaga 15237912da4SFederico VagaContesto delle funzioni 15337912da4SFederico Vaga~~~~~~~~~~~~~~~~~~~~~~~ 15437912da4SFederico Vaga 15537912da4SFederico VagaIl contesto in cui le funzioni vengono chiamate viene descritto in una 15637912da4SFederico Vagasezione chiamata ``Context``. Questo dovrebbe informare sulla possibilità 15737912da4SFederico Vagache una funzione dorma (*sleep*) o che possa essere chiamata in un contesto 15837912da4SFederico Vagad'interruzione, così come i *lock* che prende, rilascia e che si aspetta che 15937912da4SFederico Vagavengano presi dal chiamante. 16037912da4SFederico Vaga 16137912da4SFederico VagaEsempi:: 16237912da4SFederico Vaga 16337912da4SFederico Vaga * Context: Any context. 16437912da4SFederico Vaga * Context: Any context. Takes and releases the RCU lock. 16537912da4SFederico Vaga * Context: Any context. Expects <lock> to be held by caller. 16637912da4SFederico Vaga * Context: Process context. May sleep if @gfp flags permit. 16737912da4SFederico Vaga * Context: Process context. Takes and releases <mutex>. 16837912da4SFederico Vaga * Context: Softirq or process context. Takes and releases <lock>, BH-safe. 16937912da4SFederico Vaga * Context: Interrupt context. 17037912da4SFederico Vaga 17137912da4SFederico VagaValore di ritorno 17237912da4SFederico Vaga~~~~~~~~~~~~~~~~~ 17337912da4SFederico Vaga 17437912da4SFederico VagaIl valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome 17537912da4SFederico Vaga``Return``. 17637912da4SFederico Vaga 17737912da4SFederico Vaga.. note:: 17837912da4SFederico Vaga 17937912da4SFederico Vaga #) La descrizione multiriga non riconosce il termine d'una riga, per cui 18037912da4SFederico Vaga se provate a formattare bene il vostro testo come nel seguente esempio:: 18137912da4SFederico Vaga 18237912da4SFederico Vaga * Return: 18337912da4SFederico Vaga * 0 - OK 18437912da4SFederico Vaga * -EINVAL - invalid argument 18537912da4SFederico Vaga * -ENOMEM - out of memory 18637912da4SFederico Vaga 18737912da4SFederico Vaga le righe verranno unite e il risultato sarà:: 18837912da4SFederico Vaga 18937912da4SFederico Vaga Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory 19037912da4SFederico Vaga 19137912da4SFederico Vaga Quindi, se volete che le righe vengano effettivamente generate, dovete 19237912da4SFederico Vaga utilizzare una lista ReST, ad esempio:: 19337912da4SFederico Vaga 19437912da4SFederico Vaga * Return: 19537912da4SFederico Vaga * * 0 - OK to runtime suspend the device 19637912da4SFederico Vaga * * -EBUSY - Device should not be runtime suspended 19737912da4SFederico Vaga 19837912da4SFederico Vaga #) Se il vostro testo ha delle righe che iniziano con una frase seguita dai 19937912da4SFederico Vaga due punti, allora ognuna di queste frasi verrà considerata come il nome 20037912da4SFederico Vaga di una nuova sezione, e probabilmente non produrrà gli effetti desiderati. 20137912da4SFederico Vaga 20237912da4SFederico VagaDocumentare strutture, unioni ed enumerazioni 20337912da4SFederico Vaga--------------------------------------------- 20437912da4SFederico Vaga 20537912da4SFederico VagaGeneralmente il formato di un commento kernel-doc per struct, union ed enum è:: 20637912da4SFederico Vaga 20737912da4SFederico Vaga /** 20837912da4SFederico Vaga * struct struct_name - Brief description. 20937912da4SFederico Vaga * @member1: Description of member1. 21037912da4SFederico Vaga * @member2: Description of member2. 21137912da4SFederico Vaga * One can provide multiple line descriptions 21237912da4SFederico Vaga * for members. 21337912da4SFederico Vaga * 21437912da4SFederico Vaga * Description of the structure. 21537912da4SFederico Vaga */ 21637912da4SFederico Vaga 21737912da4SFederico VagaNell'esempio qui sopra, potete sostituire ``struct`` con ``union`` o ``enum`` 21837912da4SFederico Vagaper descrivere unioni ed enumerati. ``member`` viene usato per indicare i 21937912da4SFederico Vagamembri di strutture ed unioni, ma anche i valori di un tipo enumerato. 22037912da4SFederico Vaga 22137912da4SFederico VagaLa descrizione introduttiva (*brief description*) che segue il nome della 22237912da4SFederico Vagafunzione può continuare su righe successive e termina con la descrizione di 22337912da4SFederico Vagaun argomento, una linea di commento vuota, oppure la fine del commento. 22437912da4SFederico Vaga 22537912da4SFederico VagaMembri 22637912da4SFederico Vaga~~~~~~ 22737912da4SFederico Vaga 22837912da4SFederico VagaI membri di strutture, unioni ed enumerati devo essere documentati come i 22937912da4SFederico Vagaparametri delle funzioni; seguono la descrizione introduttiva e possono 23037912da4SFederico Vagaestendersi su più righe. 23137912da4SFederico Vaga 23237912da4SFederico VagaAll'interno d'una struttura o d'un unione, potete utilizzare le etichette 23337912da4SFederico Vaga``private:`` e ``public:``. I campi che sono nell'area ``private:`` non 23437912da4SFederico Vagaverranno inclusi nella documentazione finale. 23537912da4SFederico Vaga 23637912da4SFederico VagaLe etichette ``private:`` e ``public:`` devono essere messe subito dopo 23737912da4SFederico Vagail marcatore di un commento ``/*``. Opzionalmente, possono includere commenti 23837912da4SFederico Vagafra ``:`` e il marcatore di fine commento ``*/``. 23937912da4SFederico Vaga 24037912da4SFederico VagaEsempio:: 24137912da4SFederico Vaga 24237912da4SFederico Vaga /** 24337912da4SFederico Vaga * struct my_struct - short description 24437912da4SFederico Vaga * @a: first member 24537912da4SFederico Vaga * @b: second member 24637912da4SFederico Vaga * @d: fourth member 24737912da4SFederico Vaga * 24837912da4SFederico Vaga * Longer description 24937912da4SFederico Vaga */ 25037912da4SFederico Vaga struct my_struct { 25137912da4SFederico Vaga int a; 25237912da4SFederico Vaga int b; 25337912da4SFederico Vaga /* private: internal use only */ 25437912da4SFederico Vaga int c; 25537912da4SFederico Vaga /* public: the next one is public */ 25637912da4SFederico Vaga int d; 25737912da4SFederico Vaga }; 25837912da4SFederico Vaga 25937912da4SFederico VagaStrutture ed unioni annidate 26037912da4SFederico Vaga~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 26137912da4SFederico Vaga 26237912da4SFederico VagaÈ possibile documentare strutture ed unioni annidate, ad esempio:: 26337912da4SFederico Vaga 26437912da4SFederico Vaga /** 26537912da4SFederico Vaga * struct nested_foobar - a struct with nested unions and structs 26637912da4SFederico Vaga * @memb1: first member of anonymous union/anonymous struct 26737912da4SFederico Vaga * @memb2: second member of anonymous union/anonymous struct 26837912da4SFederico Vaga * @memb3: third member of anonymous union/anonymous struct 26937912da4SFederico Vaga * @memb4: fourth member of anonymous union/anonymous struct 27037912da4SFederico Vaga * @bar: non-anonymous union 27137912da4SFederico Vaga * @bar.st1: struct st1 inside @bar 27237912da4SFederico Vaga * @bar.st2: struct st2 inside @bar 27337912da4SFederico Vaga * @bar.st1.memb1: first member of struct st1 on union bar 27437912da4SFederico Vaga * @bar.st1.memb2: second member of struct st1 on union bar 27537912da4SFederico Vaga * @bar.st2.memb1: first member of struct st2 on union bar 27637912da4SFederico Vaga * @bar.st2.memb2: second member of struct st2 on union bar 27737912da4SFederico Vaga */ 27837912da4SFederico Vaga struct nested_foobar { 27937912da4SFederico Vaga /* Anonymous union/struct*/ 28037912da4SFederico Vaga union { 28137912da4SFederico Vaga struct { 28237912da4SFederico Vaga int memb1; 28337912da4SFederico Vaga int memb2; 28437912da4SFederico Vaga } 28537912da4SFederico Vaga struct { 28637912da4SFederico Vaga void *memb3; 28737912da4SFederico Vaga int memb4; 28837912da4SFederico Vaga } 28937912da4SFederico Vaga } 29037912da4SFederico Vaga union { 29137912da4SFederico Vaga struct { 29237912da4SFederico Vaga int memb1; 29337912da4SFederico Vaga int memb2; 29437912da4SFederico Vaga } st1; 29537912da4SFederico Vaga struct { 29637912da4SFederico Vaga void *memb1; 29737912da4SFederico Vaga int memb2; 29837912da4SFederico Vaga } st2; 29937912da4SFederico Vaga } bar; 30037912da4SFederico Vaga }; 30137912da4SFederico Vaga 30237912da4SFederico Vaga.. note:: 30337912da4SFederico Vaga 30437912da4SFederico Vaga #) Quando documentate una struttura od unione annidata, ad esempio 30537912da4SFederico Vaga di nome ``foo``, il suo campo ``bar`` dev'essere documentato 30637912da4SFederico Vaga usando ``@foo.bar:`` 30737912da4SFederico Vaga #) Quando la struttura od unione annidata è anonima, il suo campo 30837912da4SFederico Vaga ``bar`` dev'essere documentato usando ``@bar:`` 30937912da4SFederico Vaga 31037912da4SFederico VagaCommenti in linea per la documentazione dei membri 31137912da4SFederico Vaga~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 31237912da4SFederico Vaga 31337912da4SFederico VagaI membri d'una struttura possono essere documentati in linea all'interno 31437912da4SFederico Vagadella definizione stessa. Ci sono due stili: una singola riga di commento 31537912da4SFederico Vagache inizia con ``/**`` e finisce con ``*/``; commenti multi riga come 31637912da4SFederico Vagaqualsiasi altro commento kernel-doc:: 31737912da4SFederico Vaga 31837912da4SFederico Vaga /** 31937912da4SFederico Vaga * struct foo - Brief description. 32037912da4SFederico Vaga * @foo: The Foo member. 32137912da4SFederico Vaga */ 32237912da4SFederico Vaga struct foo { 32337912da4SFederico Vaga int foo; 32437912da4SFederico Vaga /** 32537912da4SFederico Vaga * @bar: The Bar member. 32637912da4SFederico Vaga */ 32737912da4SFederico Vaga int bar; 32837912da4SFederico Vaga /** 32937912da4SFederico Vaga * @baz: The Baz member. 33037912da4SFederico Vaga * 33137912da4SFederico Vaga * Here, the member description may contain several paragraphs. 33237912da4SFederico Vaga */ 33337912da4SFederico Vaga int baz; 33437912da4SFederico Vaga union { 33537912da4SFederico Vaga /** @foobar: Single line description. */ 33637912da4SFederico Vaga int foobar; 33737912da4SFederico Vaga }; 33837912da4SFederico Vaga /** @bar2: Description for struct @bar2 inside @foo */ 33937912da4SFederico Vaga struct { 34037912da4SFederico Vaga /** 34137912da4SFederico Vaga * @bar2.barbar: Description for @barbar inside @foo.bar2 34237912da4SFederico Vaga */ 34337912da4SFederico Vaga int barbar; 34437912da4SFederico Vaga } bar2; 34537912da4SFederico Vaga }; 34637912da4SFederico Vaga 34737912da4SFederico Vaga 34837912da4SFederico VagaDocumentazione dei tipi di dato 34937912da4SFederico Vaga------------------------------- 35037912da4SFederico VagaGeneralmente il formato di un commento kernel-doc per typedef è 35137912da4SFederico Vagail seguente:: 35237912da4SFederico Vaga 35337912da4SFederico Vaga /** 35437912da4SFederico Vaga * typedef type_name - Brief description. 35537912da4SFederico Vaga * 35637912da4SFederico Vaga * Description of the type. 35737912da4SFederico Vaga */ 35837912da4SFederico Vaga 35937912da4SFederico VagaAnche i tipi di dato per prototipi di funzione possono essere documentati:: 36037912da4SFederico Vaga 36137912da4SFederico Vaga /** 36237912da4SFederico Vaga * typedef type_name - Brief description. 36337912da4SFederico Vaga * @arg1: description of arg1 36437912da4SFederico Vaga * @arg2: description of arg2 36537912da4SFederico Vaga * 36637912da4SFederico Vaga * Description of the type. 36737912da4SFederico Vaga * 36837912da4SFederico Vaga * Context: Locking context. 36937912da4SFederico Vaga * Return: Meaning of the return value. 37037912da4SFederico Vaga */ 37137912da4SFederico Vaga typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); 37237912da4SFederico Vaga 37337912da4SFederico VagaMarcatori e riferimenti 37437912da4SFederico Vaga----------------------- 37537912da4SFederico Vaga 37637912da4SFederico VagaAll'interno dei commenti di tipo kernel-doc vengono riconosciuti i seguenti 37737912da4SFederico Vaga*pattern* che vengono convertiti in marcatori reStructuredText ed in riferimenti 37837912da4SFederico Vagadel `dominio Sphinx per il C`_. 37937912da4SFederico Vaga 38037912da4SFederico Vaga.. attention:: Questi sono riconosciuti **solo** all'interno di commenti 38137912da4SFederico Vaga kernel-doc, e **non** all'interno di documenti reStructuredText. 38237912da4SFederico Vaga 38337912da4SFederico Vaga``funcname()`` 38437912da4SFederico Vaga Riferimento ad una funzione. 38537912da4SFederico Vaga 38637912da4SFederico Vaga``@parameter`` 38737912da4SFederico Vaga Nome di un parametro di una funzione (nessun riferimento, solo formattazione). 38837912da4SFederico Vaga 38937912da4SFederico Vaga``%CONST`` 39037912da4SFederico Vaga Il nome di una costante (nessun riferimento, solo formattazione) 39137912da4SFederico Vaga 39237912da4SFederico Vaga````literal```` 39337912da4SFederico Vaga Un blocco di testo che deve essere riportato così com'è. La rappresentazione 39437912da4SFederico Vaga finale utilizzerà caratteri a ``spaziatura fissa``. 39537912da4SFederico Vaga 39637912da4SFederico Vaga Questo è utile se dovete utilizzare caratteri speciali che altrimenti 39737912da4SFederico Vaga potrebbero assumere un significato diverso in kernel-doc o in reStructuredText 39837912da4SFederico Vaga 39937912da4SFederico Vaga Questo è particolarmente utile se dovete scrivere qualcosa come ``%ph`` 40037912da4SFederico Vaga all'interno della descrizione di una funzione. 40137912da4SFederico Vaga 40237912da4SFederico Vaga``$ENVVAR`` 40337912da4SFederico Vaga Il nome di una variabile d'ambiente (nessun riferimento, solo formattazione). 40437912da4SFederico Vaga 40537912da4SFederico Vaga``&struct name`` 40637912da4SFederico Vaga Riferimento ad una struttura. 40737912da4SFederico Vaga 40837912da4SFederico Vaga``&enum name`` 40937912da4SFederico Vaga Riferimento ad un'enumerazione. 41037912da4SFederico Vaga 41137912da4SFederico Vaga``&typedef name`` 41237912da4SFederico Vaga Riferimento ad un tipo di dato. 41337912da4SFederico Vaga 41437912da4SFederico Vaga``&struct_name->member`` or ``&struct_name.member`` 41537912da4SFederico Vaga Riferimento ad un membro di una struttura o di un'unione. Il riferimento sarà 41637912da4SFederico Vaga la struttura o l'unione, non il memembro. 41737912da4SFederico Vaga 41837912da4SFederico Vaga``&name`` 41937912da4SFederico Vaga Un generico riferimento ad un tipo. Usate, preferibilmente, il riferimento 42037912da4SFederico Vaga completo come descritto sopra. Questo è dedicato ai commenti obsoleti. 42137912da4SFederico Vaga 42237912da4SFederico VagaRiferimenti usando reStructuredText 42337912da4SFederico Vaga~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 42437912da4SFederico Vaga 425ac771142SFederico VagaNei documenti reStructuredText non serve alcuna sintassi speciale per 426ac771142SFederico Vagafare riferimento a funzioni e tipi definiti nei commenti 427ac771142SFederico Vagakernel-doc. Sarà sufficiente terminare i nomi di funzione con ``()``, 428ac771142SFederico Vagae scrivere ``struct``, ``union``, ``enum``, o ``typedef`` prima di un 429ac771142SFederico Vagatipo. Per esempio:: 43037912da4SFederico Vaga 431ac771142SFederico Vaga See foo() 432ac771142SFederico Vaga See struct foo. 433ac771142SFederico Vaga See union bar. 434ac771142SFederico Vaga See enum baz. 435ac771142SFederico Vaga See typedef meh. 43637912da4SFederico Vaga 437ac771142SFederico VagaTuttavia, la personalizzazione dei collegamenti è possibile solo con 438ac771142SFederico Vagala seguente sintassi:: 43937912da4SFederico Vaga 440ac771142SFederico Vaga See :c:func:`my custom link text for function foo <foo>`. 441ac771142SFederico Vaga See :c:type:`my custom link text for struct bar <bar>`. 44237912da4SFederico Vaga 44337912da4SFederico Vaga 44437912da4SFederico VagaCommenti per una documentazione generale 44537912da4SFederico Vaga---------------------------------------- 44637912da4SFederico Vaga 44737912da4SFederico VagaAl fine d'avere il codice ed i commenti nello stesso file, potete includere 44837912da4SFederico Vagadei blocchi di documentazione kernel-doc con un formato libero invece 44937912da4SFederico Vagache nel formato specifico per funzioni, strutture, unioni, enumerati o tipi 45037912da4SFederico Vagadi dato. Per esempio, questo tipo di commento potrebbe essere usato per la 45137912da4SFederico Vagaspiegazione delle operazioni di un driver o di una libreria 45237912da4SFederico Vaga 45337912da4SFederico VagaQuesto s'ottiene utilizzando la parola chiave ``DOC:`` a cui viene associato 45437912da4SFederico Vagaun titolo. 45537912da4SFederico Vaga 45637912da4SFederico VagaGeneralmente il formato di un commento generico o di visione d'insieme è 45737912da4SFederico Vagail seguente:: 45837912da4SFederico Vaga 45937912da4SFederico Vaga /** 46037912da4SFederico Vaga * DOC: Theory of Operation 46137912da4SFederico Vaga * 46237912da4SFederico Vaga * The whizbang foobar is a dilly of a gizmo. It can do whatever you 46337912da4SFederico Vaga * want it to do, at any time. It reads your mind. Here's how it works. 46437912da4SFederico Vaga * 46537912da4SFederico Vaga * foo bar splat 46637912da4SFederico Vaga * 46737912da4SFederico Vaga * The only drawback to this gizmo is that is can sometimes damage 46837912da4SFederico Vaga * hardware, software, or its subject(s). 46937912da4SFederico Vaga */ 47037912da4SFederico Vaga 47137912da4SFederico VagaIl titolo che segue ``DOC:`` funziona da intestazione all'interno del file 47237912da4SFederico Vagasorgente, ma anche come identificatore per l'estrazione di questi commenti di 47337912da4SFederico Vagadocumentazione. Quindi, il titolo dev'essere unico all'interno del file. 47437912da4SFederico Vaga 475da1d9cafSFederico Vaga======================================= 47637912da4SFederico VagaIncludere i commenti di tipo kernel-doc 47737912da4SFederico Vaga======================================= 47837912da4SFederico Vaga 47937912da4SFederico VagaI commenti di documentazione possono essere inclusi in un qualsiasi documento 48037912da4SFederico Vagadi tipo reStructuredText mediante l'apposita direttiva nell'estensione 48137912da4SFederico Vagakernel-doc per Sphinx. 48237912da4SFederico Vaga 48337912da4SFederico VagaLe direttive kernel-doc sono nel formato:: 48437912da4SFederico Vaga 48537912da4SFederico Vaga .. kernel-doc:: source 48637912da4SFederico Vaga :option: 48737912da4SFederico Vaga 48837912da4SFederico VagaIl campo *source* è il percorso ad un file sorgente, relativo alla cartella 48937912da4SFederico Vagaprincipale dei sorgenti del kernel. La direttiva supporta le seguenti opzioni: 49037912da4SFederico Vaga 49137912da4SFederico Vagaexport: *[source-pattern ...]* 49237912da4SFederico Vaga Include la documentazione per tutte le funzioni presenti nel file sorgente 49337912da4SFederico Vaga (*source*) che sono state esportate utilizzando ``EXPORT_SYMBOL`` o 49437912da4SFederico Vaga ``EXPORT_SYMBOL_GPL`` in *source* o in qualsiasi altro *source-pattern* 49537912da4SFederico Vaga specificato. 49637912da4SFederico Vaga 49737912da4SFederico Vaga Il campo *source-patter* è utile quando i commenti kernel-doc sono stati 49837912da4SFederico Vaga scritti nei file d'intestazione, mentre ``EXPORT_SYMBOL`` e 49937912da4SFederico Vaga ``EXPORT_SYMBOL_GPL`` si trovano vicino alla definizione delle funzioni. 50037912da4SFederico Vaga 50137912da4SFederico Vaga Esempi:: 50237912da4SFederico Vaga 50337912da4SFederico Vaga .. kernel-doc:: lib/bitmap.c 50437912da4SFederico Vaga :export: 50537912da4SFederico Vaga 50637912da4SFederico Vaga .. kernel-doc:: include/net/mac80211.h 50737912da4SFederico Vaga :export: net/mac80211/*.c 50837912da4SFederico Vaga 50937912da4SFederico Vagainternal: *[source-pattern ...]* 51037912da4SFederico Vaga Include la documentazione per tutte le funzioni ed i tipi presenti nel file 51137912da4SFederico Vaga sorgente (*source*) che **non** sono stati esportati utilizzando 51237912da4SFederico Vaga ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` né in *source* né in qualsiasi 51337912da4SFederico Vaga altro *source-pattern* specificato. 51437912da4SFederico Vaga 51537912da4SFederico Vaga Esempio:: 51637912da4SFederico Vaga 51737912da4SFederico Vaga .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 51837912da4SFederico Vaga :internal: 51937912da4SFederico Vaga 520b67aa4efSFederico Vagaidentifiers: *[ function/type ...]* 521b67aa4efSFederico Vaga Include la documentazione per ogni *function* e *type* in *source*. 522b67aa4efSFederico Vaga Se non vengono esplicitamente specificate le funzioni da includere, allora 523b67aa4efSFederico Vaga verranno incluse tutte quelle disponibili in *source*. 524b67aa4efSFederico Vaga 525b67aa4efSFederico Vaga Esempi:: 526b67aa4efSFederico Vaga 527b67aa4efSFederico Vaga .. kernel-doc:: lib/bitmap.c 528b67aa4efSFederico Vaga :identifiers: bitmap_parselist bitmap_parselist_user 529b67aa4efSFederico Vaga 530b67aa4efSFederico Vaga .. kernel-doc:: lib/idr.c 531b67aa4efSFederico Vaga :identifiers: 532b67aa4efSFederico Vaga 533b67aa4efSFederico Vagafunctions: *[ function ...]* 534b67aa4efSFederico Vaga Questo è uno pseudonimo, deprecato, per la direttiva 'identifiers'. 535b67aa4efSFederico Vaga 53637912da4SFederico Vagadoc: *title* 53737912da4SFederico Vaga Include la documentazione del paragrafo ``DOC:`` identificato dal titolo 53837912da4SFederico Vaga (*title*) all'interno del file sorgente (*source*). Gli spazi in *title* sono 53937912da4SFederico Vaga permessi; non virgolettate *title*. Il campo *title* è utilizzato per 54037912da4SFederico Vaga identificare un paragrafo e per questo non viene incluso nella documentazione 54137912da4SFederico Vaga finale. Verificate d'avere l'intestazione appropriata nei documenti 54237912da4SFederico Vaga reStructuredText. 54337912da4SFederico Vaga 54437912da4SFederico Vaga Esempio:: 54537912da4SFederico Vaga 54637912da4SFederico Vaga .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 54737912da4SFederico Vaga :doc: High Definition Audio over HDMI and Display Port 54837912da4SFederico Vaga 54937912da4SFederico VagaSenza alcuna opzione, la direttiva kernel-doc include tutti i commenti di 55037912da4SFederico Vagadocumentazione presenti nel file sorgente (*source*). 55137912da4SFederico Vaga 55237912da4SFederico VagaL'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare 55337912da4SFederico Vagain ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato 55437912da4SFederico Vagalo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione 55537912da4SFederico Vagadai file sorgenti. 55637912da4SFederico Vaga 55737912da4SFederico VagaCome utilizzare kernel-doc per generare pagine man 55837912da4SFederico Vaga-------------------------------------------------- 55937912da4SFederico Vaga 56037912da4SFederico VagaSe volete utilizzare kernel-doc solo per generare delle pagine man, potete 56137912da4SFederico Vagafarlo direttamente dai sorgenti del kernel:: 56237912da4SFederico Vaga 56337912da4SFederico Vaga $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man 564