Come fare riferimento a specifiche aree di codice nella documentazione?

Se capisco bene, sembra che tu abbia un problema unico. Quello che vuoi fare è fare riferimento a una specifica riga di codice nei commenti che sono scritti in qualche altra parte dello stesso codice.

Di solito non mi imbatto in tali scenari in cui ho bisogno di fare riferimento a una linea exect # in qualche commento scritto altrove - generalmente il codice è documentato esattamente dove è scritto.

Non conosco alcun modo standard per farlo, ma in cima alla mia testa ...

Puoi fare riferimento a porzioni di codice tramite il suo contesto, cioè le cose che li circondano.

Notice above the definition of func1() that such-and-such happens

Note that just after the for loop that iterates over recordXYZItr, that we are also calling the method gc()

Caution: In the method yahoo(), right after the declaration of variable PQ, we are also swapping the values in A and B, so the mapABC object there also needs to be copied

Un altro modo è aggiungere tag descrittivi. Invece di qualcosa come 38FECD4F , puoi dire Some XYZ implementation o BUGFIX 1474 , quindi fare riferimento a questo altrove.

Dipende molto da come è stato scritto il codice, e capisco che possa indurre un sacco di refactoring che non sei qui per fare.

Ma ... se è necessario fare riferimento a una specifica linea di codice come a un'unità intera, non significherebbe che il suo codice che rappresenta un'operazione astratta, e quindi potrebbe essere refactored nel proprio metodo / funzione? Una volta che è in un metodo, è piuttosto facile, basta fare riferimento a namespace.class.method Ovviamente questo significa avere metodi molto piccoli, lunghi circa 5-10 linee o anche meno. Con Doxygen, puoi mettere la documentazione in cima al metodo, e rimarrebbe sempre sincronizzata con il nome del metodo / classe / spazio dei nomi.

Ti suggerisco di adottare un approccio diverso, diverso dal collegamento da una documentazione esterna al codice al codice:

1. aggiungi commenti al tuo codice, utilizzando uno strumento come doxygen .

2. se vi è la necessità di spiegare alcuni concetti in modo più dettagliato di quanto sia adatto nella documentazione del codice (appena creato), è sempre possibile creare un documento separato e collegarlo a questo.

In questo modo è possibile generare facilmente la documentazione come pagina Web o PDF e rimane coerente con il codice. L'utilizzo di alcuni tag artificiali diventerà molto difficile da mantenere e ancora più difficile da comprendere per chi non lo sapesse.