mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
electron/docs-translations/it-IT/styleguide.md
Gioggio 3b45f5a8e9 📝 Add styleguide.md 
[ci skip]
2016-09-22 21:07:13 +02:00

6.6 KiB
Raw Blame History

Guida allo Stile della Documentazione

Queste sono le linee guida per la stesura della documentazione di Electron.

Titoli

  • Ogni pagina deve avere un singolo titolo di livello # all'inizio.
  • I capitoli di una stessa pagina devono avere titoli di livello ##.
  • I sotto-capitoli devono avere un numero crescente di # a seconda del loro livello di annidamento.
  • Tutte le parole nel titolo della pagina devono iniziare con la lettera maiuscola, a eccezione delle congiunzioni come "di" ed "e".
  • Solo la prima lettera della prima parola di un capitolo deve essere maiuscola.

Prendendo Guida Rapida come esempio:

# Guida Rapida

...

## Processo principale

...

## Processo di rendering

...

## Esegui la tua app

...

### Crea una distribuzione

...

### Electron scaricato manualmente

...

Esistono eccezioni a queste regole per quanto riguarda la documentazione delle API.

Regole markdown

  • Usa bash invece di cmd nei blocchi di codice (per via della diversa evidenziazione della sintassi).
  • Le linee devono essere lunghe al massimo 80 caratteri.
  • Non annidare le liste per più di due livelli (per via del rendering compiuto da markdown).
  • Tutti i blocchi di codice js o javascript sono analizzati con standard-markdown.

Documentazione API

Le regole seguenti vengono applicate solo alla documentazione delle API.

Titolo della pagina

Ogni pagina deve avere come titolo il nome dell'oggetto a cui si riferisce seguito da require('electron'), come ad esempio BrowserWindow, autoUpdater e session.

Sotto il titolo della pagina deve esserci una descrizione della lunghezza di una linea che comincia con >.

Prendendo session come esempio:

# session

> Gestisce le sessioni browser, cookies, cache, impostazioni proxy, etc.

Metodi ed eventi dei moduli

Per i moduli che non sono classi, i loro metodi ed eventi devono essere elencati sotto i capitoli ## Metodi ed ## Eventi.

Prendendo autoUpdate come esempio:

# autoUpdater

## Eventi

### Evento: 'error'

## Metodi

### `autoUpdater.setFeedURL(url[, requestHeaders])`

Classi

  • Le classi API e le classi che sono parte di moduli devono essere elencate sotto un capitolo ## Classe: NomeDellaClasse.
  • Una pagina può avere più classi.
  • I costruttoi devono essere elencati con un titolo di livello ###.
  • I Metodi Statici (Inglese) devono essere elencati sotto un capitolo ### Metodi Statici.
  • I Metodi di Istanza (Inglese) devono essere elencati sotto un capitolo ### Metodi di Istanza.
  • Gli Eventi di Istanza devono essere elencati sotto un capitolo ## Eventi di Istanza.
  • Le Proprietà di Istanza devono essere elencate sotto un capitolo ## Proprietà di Istanza.

Prendendo le classi Session e Cookies come esempi:

# session

## Metodi

### session.fromPartition(partition)

## Proprietà

### session.defaultSession

## Classe: Session

### Eventi di Istanza

#### Evento: 'will-download'

### Metodi di Istanza

#### `ses.getCacheSize(callback)`

### Proprietà di Istanza

#### `ses.cookies`

## Classe: Cookies

### Metodi di Istanza

#### `cookies.get(filter, callback)`

Metodi

Il capitolo dei metodi deve seguire il seguente formato:

### `objectName.methodName(required[, optional]))`

* `required` String
* `optional` Integer (optional)

...

Il titolo può essere di livello ### o #### a seconda che sia un metodo di un modulo o di una classe.

Per i moduli, il nomeOggetto è il nome del modulo. Per le classi, deve essere il nome dell'istanza della classe e non deve essere lo stesso del modulo.

Per esempio, i metodi della classe Session sotto il modulo session devono usare ses come nomeOggetto.

I parametri opzionali sono caratterizzati sia dalle parentesi quadre [] che circondano il parametro, sia dalla virgola obbligatoria in caso il parametro ne segua un altro.

required[, optional]

Sotto ogni metodo si trovano informazioni dettagliate su ogni parametro. Il tipo di parametro è caratterizzato da uno dei tipi di dati comuni:

Se un parametro o un metodo sono limitati a certe piattaforme, esse sono segnalate, dopo il tipo di dato, attraverso l'uso di una lista di elementi in corsivo e delimitati da uno spazio. I valori possono essere macOS, Windows e Linux.

* `animate` Boolean (optional) _macOS_ _Windows_

I parametri di tipo Array devono specificare nella descrizione sottostante che elementi può contenere l'array.

La descrizione per i parametri di tipo Funzione dovrebbero rendere chiaro come sia possibile chiamarli, ed elencare i tipi di parametri che vi saranno passati.

Eventi

Il capitolo degli eventi deve seguire il seguente formato:

### Evento: 'wake-up'

Ritorna:

* `time` String

...

Il titolo può essere di livello ### o #### a seconda che sia di un evento di un modulo o di una classe.

I parametri di un evento seguono le stesse regole di quelli dei metodi.

Proprietà

Il capitolo delle proprietà deve seguire il seguente formato:

### session.defaultSession

...

Il titolo può essere di livello ### o #### a seconda che sia una proprietà di un metodo o di una classe.

Traduzioni della Documentazione

Le traduzioni della documentazione di Electron si trovano nella cartella docs-translations.

Per aggiungere un altro set (o set parziale):

  • Crea una sottocartella che abbia come nome il codice della lingua.
  • Traduci i file.
  • Aggiorna il file README.md dentro la cartella della lingua in modo che reindirizzi ai file che hai tradotto.
  • Aggiungi un collegamento alla cartella della traduzione nel README principale di Electron.

Nota che tutti i file nella cartella docs-translations devono includere solo i file tradotti. I file originali in inglese non devono essere copiati lì.