Documentazione di un membro non esistente con Doxygen

Question

Sto provando a documentare una classe Python utilizzando Doxygen. La classe espone un insieme di proprietà su d-bus, ma questi non hanno getter/setter pubblici corrispondenti nella classe python. Invece, sono implementati attraverso un'interfaccia delle proprietà del d-bus (Set/Get/GetAll/Introspect).

Quello che voglio fare è quello di essere in grado di documentare queste proprietà utilizzando qualcosa di simile:

## @property package::Class::Name description

L'intero pacchetto :: Class funziona (lo stesso metodo trova funzioni, in modo che trova il giusto classe).

Quando si esegue doxygen ricevo il seguente errore:

warning: documented function ``package::Class::Name' was not declared or defined.

posso vivere con un avvertimento, ma purtroppo la proprietà non compare nella documentazione generata per la classe, quindi non è solo un avvertimento, ma è anche silenziato.

Quindi, la mia domanda è: come, se posso, faccio apparire il membro della proprietà non esistente nei documenti generati?

Answer 1

Definire l'attributo all'interno di un blocco if 0::

## @class X 
## @brief this is useless 
class X: 
    if 0: 
     ## @brief whatevs is a property that doesn't exist in spacetime 
     ## 
     ## It is designed to make bunny cry. 
     whatevs = property 

Questo farà sì che esista nella documentazione (testato con doxygen 1.8.1.2-1 su debian-squeeze). L'attributo non verrà mai creato per esistere in fase di runtime, e infatti sembra che l'ottimizzatore bytecode python rimuova del tutto l'istruzione e il suo corpo.

Answer 2

Ho esaminato qualcosa di simile in precedenza e non sono riuscito a trovare un modo diretto per convincere Doxygen a documentare un membro indefinito. Ci sono due opzioni di base che puoi usare qui:

1.) generare un oggetto fittizio (o membri fittizi) per doxygen all'inventario che non esiste realmente nel codice live.

2.) Se le regolazioni necessarie sono abbastanza prevedibili e regolari, è possibile scrivere un INPUT_FILTER per doxygen che preleva i file e li converte prima di analizzare. Ci sono alcuni problemi con questo metodo - soprattutto se si pianifica di includere il codice nella documentazione e il filtro deve aggiungere/rimuovere linee dal file, i numeri di linea che indica saranno spenti e tutte le finestre di codice mostrate con il la documentazione sarà disattivata da quel numero di righe. Puoi anche controllare l'opzione per filtrare le sorgenti visualizzate per regolarle, ma a seconda di chi sia il consumatore della tua documentazione, potrebbe essere difficile confondere la copia in Doxygen per non corrispondere perfettamente a ciò che è nella fonte reale.

Nel nostro caso utilizziamo uno script python che Doxygen viene eseguito dalla riga di comando con il percorso del file come arg. Leggiamo il file indicato e scriviamo ciò che vogliamo che Doxygen interpreti invece di stdout. Se è necessario filtrare anche le copie di origine visualizzate in doxygen, è possibile impostare FILTER_SOURCE_FILES su YES.