Dokumentieren Sie Python-Code mit Doxygen

Wenn ich den Python-Code in Doxygen dokumentiere, lasse ich das Memo, weil es passt.

Kommentare im Docstring-Format in Python werden von der Bearbeitungsunterstützungsfunktion von VScode angezeigt, wenn der Cursor auf die Funktion gesetzt wird.

■ Beispiel für einen Kommentar im Dokumentzeichenfolgenformat

def leftCosets(self, H: FiniteGroup) -> Set[Set[GroupElement]]:
	"""
	@brief Calculates left cosets of H in self.

	@details foo

	:param H: subGroup of self
	:return:

	@note bar
	"""

	cosets = {frozenset(copy.deepcopy(H.elements)),}
	remain = self.elements - H.elements

	while len(remain) > 0:
		#~ Ausgelassen ~

	return cosets

Dies ist praktisch, da Sie es im Kommentar überprüfen können, ohne zur Position der Funktionsdefinition zu wechseln, indem Sie den Cursor auf die Funktion bewegen.

Das Dokumentzeichenfolgenformat sieht jedoch nicht gut aus, wenn es in Doxygen dokumentiert ist, da "keine speziellen Befehle in Doxygen unterstützt werden".

• Ich habe ein Python-Projekt in Doxygen dokumentiert, aber die Parameter sind nicht richtig aufgelistet.

Daher verwenden wir einen Filter, der das Dokumentzeichenfolgenformat in das Sauerstoffformat konvertiert.

■ Filtern, um das Dokumentzeichenfolgenformat in das Doxygen-Format zu konvertieren doxyfilter_python(GitHub)

Dieser Filter konvertiert das Dokumentzeichenfolgenformat in das Doxygen-Format und übergibt es an Doxygen.

■ Beispiel für einen Kommentar im Sauerstoffformat

	##
	#@brief Calculates left cosets of H in self.
	#@details foo
	#
	#@param H (FiniteGroup) subGroup of self
	#@return (Set[Set[GroupElement]])
	#
	#@note bar
	def leftCosets(self, H: FiniteGroup) -> Set[Set[GroupElement]]:
	cosets = {frozenset(copy.deepcopy(H.elements)),}
	remain = self.elements - H.elements

	while len(remain) > 0:
		#~ Ausgelassen ~

	return cosets

• Achtung * Wenn Sie dies wie in einer Windows-Umgebung verwenden, funktioniert es mit cp932 und japanische Zeichen werden verstümmelt. Bearbeiten Sie in einer Windows-Umgebung doxyfilter_python.py und geben Sie die Codierung "utf-8" an.

python：doxyfilter_python.py

import io

#~ Ausgelassen ~ durchführen_Fügen Sie am Anfang der fh-Funktion die folgende Zeile hinzu
        sys.stdout = io.TextIOWrapper(sys.stdout.buffer,encoding='utf-8')


#~ Ausgelassen ~ Geben Sie die Codierung im geöffneten Teil der Hauptfunktion an.
        with open(file, 'r',encoding='utf-8') as fh:

■ Vorsichtsmaßnahmen wie Doxygen-Einstellungen

Python ähnelt eher Java als C oder C ++. Setzen Sie daher OPTMIZE_OUTPUT_JAVA in der Konfigurationsdatei auf YES.

Aus "Kommentarblöcke in Python"

• Achten Sie darauf, eine Zeile zwischen @brief und @details zu lassen. Andernfalls werden die Elemente im VS-Code-Tooltip als eine Zeile angezeigt, ohne zu unterbrechen.
• Stellen Sie sicher, dass Sie einen Dateikommentar einfügen. Andernfalls wird die globale Methode nicht dokumentiert.

Aus "Verwenden von Doxygen mit Python3 mit VS Code Editing Assistance"

--Expert tab-> Topics-> Input-> Geben Sie doxyfilter_python.py mit dem vollständigen Pfad in INPUT_FILTER an.

Für die Referenzseite ("Verwenden Sie Doxygen mit Python3, während Sie die Unterstützung für die VS-Code-Bearbeitung nutzen")

Stellen Sie sicher, dass Sie doxyfilter_python.py mit dem vollständigen Pfad angeben und explizit angeben, dass es in python3 ausgeführt wird (andernfalls ist es fehlgeschlagen).

Obwohl es geschrieben ist, scheint es nicht notwendig zu sein, python3 in einer Umgebung anzugeben, in der nur python3.x-Serien enthalten sind.