Come si scrive la documentazione pacchetto? [chiuso]

StackOverflow https://stackoverflow.com/questions/3086081

Domanda

Non ho ben capito un flusso di lavoro ragionevole per la creazione dei pacchetti e scrivere la loro documentazione.

I vogliono, gran parte del processo (e la documentazione) il più possibile per essere generato automaticamente.

Il modo più ovvio per fare questo sembra essere quello di utilizzare package.skeleton per creare i file del pacchetto di base, quindi a livello di codice sovrascrivere il file DESCRIPTION ei file Rd. Il problema di questo è che si perde poi i campi generati automaticamente che assicurano di aver ricordato di documentare tutti i parametri giusti.

Mi piacerebbe sapere come si andare a costruire pacchetti e la scrittura di documentazione. Ci sono strumenti a disposizione per rendere il processo più semplice? ( roxygen sembra che è stato progettato per questo genere di cose ;?? c'è un buon tutorial per essa e non ci sono alternative)

È stato utile?

Soluzione

Io uso roxygen per tutti i miei progetti. Per un esempio, sfogliare la fonte per webvis pacchetto . Hadley utilizza anche roxygen per la sua documentazione (ad esempio, vedere il suo lubridate pacchetto ).

Per quanto a mia conoscenza, roxygen non è documentato molto al di là del vigette (dare un'occhiata al il roxygen homepage ).

Roxygen è buono perché porta alla programmazione letterata, nel senso che la documentazione e il codice sono side-by-side. Questo rende anche il processo di documentazione un po 'più facile dal momento che si sta lavorando con tutto in una volta. Lo consiglio vivamente, e non svilupperò tutti i pacchetti senza di essa, a questo punto.

Detto questo, non automatizzare la documentazione, nel senso che alcuni strumenti di documentazione generazione fanno (per esempio javadoc): interpreta roxygen R commenti che siano adeguatamente formattati, ma non interpreta il codice R in alcun modo <. / p>

Per quanto riguarda la creazione del pacchetto in generale: package-skeleton è grande per i principianti. Dopo aver creato un paio di pacchetti che si può trovare più facile in futuro solo per creare tutte le directory, NAMESPACE, ecc a mano. Soprattutto se avete intenzione di seguire alcune delle altre pratiche, come ad esempio tra cui una directory demo, utilizzando roxygen, scrivendo una vignetta, o compreso il codice sorgente in altre lingue.

Infine, gestisco i miei pacchetti in Eclipse (StatET); molti dei di IDE hanno vista "progetto" che aiutano la gestione della struttura del pacchetto, per cui si potrebbe anche decidere di utilizzare un editor più avanzato.

Altri suggerimenti

Per quanto riguarda le risorse roxygen, molti altri hanno dato emerso, un paio di più sono emersi, per citare i miei appunti :

  

Spesso, quando ho google Roxygen o Roxygen2 ho scoperta guai   documentazione. Ecco una raccolta di alcune risorse chiave:

     
Autorizzato sotto: CC-BY-SA insieme a attribuzione
Non affiliato a StackOverflow
scroll top