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