Italian

Warning

In caso di dubbi sulla correttezza del contenuto di questa traduzione, l’unico riferimento valido è la documentazione ufficiale in inglese. Per maggiori informazioni consultate le avvertenze.

Original:

How to write kernel documentation

Includere gli i file di intestazione uAPI

Qualche volta è utile includere dei file di intestazione e degli esempi di codice C al fine di descrivere l’API per lo spazio utente e per generare dei riferimenti fra il codice e la documentazione. Aggiungere i riferimenti ai file dell’API dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi d’avviso se un simbolo non viene trovato nella documentazione. Questo permette di mantenere allineate la documentazione della uAPI (API spazio utente) con le modifiche del kernel. Il programma parse_headers.pl genera questi riferimenti. Esso dev’essere invocato attraverso un Makefile, mentre si genera la documentazione. Per avere un esempio su come utilizzarlo all’interno del kernel consultate Documentation/userspace-api/media/Makefile.

parse_headers.pl

NOME

parse_headers.pl - analizza i file C al fine di identificare funzioni, strutture, enumerati e definizioni, e creare riferimenti per Sphinx

SINTASSI

parse_headers.pl [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]

Dove <options> può essere: --debug, --usage o --help.

OPZIONI

--debug

Lo script viene messo in modalità verbosa, utile per il debugging.

--usage

Mostra un messaggio d’aiuto breve e termina.

--help

Mostra un messaggio d’aiuto dettagliato e termina.

DESCRIZIONE

Converte un file d’intestazione o un file sorgente C (C_FILE) in un testo reStructuredText incluso mediante il blocco ..parsed-literal con riferimenti alla documentazione che descrive l’API. Opzionalmente, il programma accetta anche un altro file (EXCEPTIONS_FILE) che descrive quali elementi debbano essere ignorati o il cui riferimento deve puntare ad elemento diverso dal predefinito.

Il file generato sarà disponibile in (OUT_FILE).

Il programma è capace di identificare define, funzioni, strutture, tipi di dato, enumerati e valori di enumerati, e di creare i riferimenti per ognuno di loro. Inoltre, esso è capace di distinguere le #define utilizzate per specificare i comandi ioctl di Linux.

Il file EXCEPTIONS_FILE contiene due tipi di dichiarazioni: ignore o replace.

La sintassi per ignore è:

ignore tipo nome

La dichiarazione ignore significa che non verrà generato alcun riferimento per il simbolo name di tipo tipo.

La sintassi per replace è:

replace tipo nome nuovo_valore

La dichiarazione replace significa che verrà generato un riferimento per il simbolo namedi tipo tipo, ma, invece di utilizzare il valore predefinito, verrà utilizzato il valore nuovo_valore.

Per entrambe le dichiarazioni, il tipo può essere uno dei seguenti:

ioctl

La dichiarazione ignore o replace verrà applicata su definizioni di ioctl come la seguente:

#define VIDIOC_DBG_S_REGISTER _IOW(‘V’, 79, struct v4l2_dbg_register)

define

La dichiarazione ignore o replace verrà applicata su una qualsiasi #define trovata in C_FILE.

typedef

La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef in C_FILE.

struct

La dichiarazione ignore o replace verrà applicata ai nomi di strutture in C_FILE.

enum

La dichiarazione ignore o replace verrà applicata ai nomi di enumerati in C_FILE.

symbol

La dichiarazione ignore o replace verrà applicata ai nomi di valori di enumerati in C_FILE.

Per le dichiarazioni di tipo replace, il campo new_value utilizzerà automaticamente i riferimenti :c:type: per typedef, enum e struct. Invece, utilizzerà :ref: per ioctl, define e symbol. Il tipo di riferimento può essere definito esplicitamente nella dichiarazione stessa.

ESEMPI

ignore define _VIDEODEV2_H

Ignora una definizione #define _VIDEODEV2_H nel file C_FILE.

ignore symbol PRIVATE

In un enumerato come il seguente:

enum foo { BAR1, BAR2, PRIVATE };

Non genererà alcun riferimento per PRIVATE.

replace symbol BAR1 :c:type:`foo` replace symbol BAR2 :c:type:`foo`

In un enumerato come il seguente:

enum foo { BAR1, BAR2, PRIVATE };

Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C.

BUGS

Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com>