Ich bin gerade dabei für meinen Kernel eine Doxygen Dokumentation anzulegen, da sich ein paar Leute gefunden haben, die interessiert sind, daran mitzuarbeiten. Außerdem erleichtert das auch mir die Arbeit am Kernel, denn manche Funktionen vergisst man gerne einmal.
Der Kernel ist in C geschrieben. Ein paar Fetzen Assembler sind auch dabei.
Nun stellt sich natürlich die Frage wie man ein so (doch) großes Projekt sinnvoll und vorallem übersichtlich mit Doxygen Kommentaren ausstattet. Ich kenne mich leider recht wenig mit Doxygen aus, deshalb habe ich jetzt ein paar Fragen:
WO wird kommentiert? In den Headerdateien (die eigentlich FAST alles noch einmal enthalten) oder in den Quelldateien?
WIE wird kommentiert? Ich habe nun schon einige unterschiedliche Varianten gesehen, welche ist die Beste, wenn es eine gibt, und wenn ja, warum?
Dann noch ein zweites WO:
Wie platziere ich die Kommentare am sinnvollsten in den Dateien?
Ich hab das jetzt mal testweise für einen Header gemacht, das würde dann so aussehen:
Code: Alles auswählen
#ifndef __KERNEL__PHYSICALMEMORY__HEADER__
#define __KERNEL__PHYSICALMEMORY__HEADER__
#include "library/types.h"
/**
* \def MAKRO_SET_BIT(x)
* \brief Sets bit number x
*/
#define MAKRO_SET_BIT(x) (( 1 << ( (x) )))
/**
* \def FRAME_SIZE
* \brief The size of a frame in bytes
*/
#define FRAME_SIZE 0x1000
/**
* \def PHYSICAL_MAPSIZE_MB
* \brief The amount of memory managed by a single map in megabytes
*/
#define PHYSICAL_MAPSIZE_MB 8lu
/**
* \def PHYSICAL_MAPSIZE_BYTES
* \brief The amount of memory managed by a single map in bytes
*/
#define PHYSICAL_MAPSIZE_BYTES MB_TO_BYTES(PHYSICAL_MAPSIZE_MB)
/**
* \def ADDRESS_TO_FRAME(Address)
* \brief The address of the given frame
*/
#define ADDRESS_TO_FRAME(Address) (Address >> 12)
/**
* \def FRAME_TO_ADDRESS(Frame)
* \brief The frame of the given address
*/
#define FRAME_TO_ADDRESS(Frame) (Frame << 12)
/**
* \def START_OF_FRAME(ADDR)
* \brief The startaddress of the actual frame
*/
#define START_OF_FRAME(ADDR) ((ADDR)&(0xFFFFF000))
/**
* \def START_OF_NEXT_FRAME(ADDR)
* \brief The startaddress of the next frame
*/
#define START_OF_NEXT_FRAME(ADDR) START_OF_FRAME((ADDR)+FRAME_SIZE)
/**
* \def PHYSICAL_OK
* \brief Magic value to show everything is ok
*/
#define PHYSICAL_OK 1
/**
* \def PHYSICAL_ERROR
* \brief Magic value to show that there is an error
*/
#define PHYSICAL_OK 0
//-------------------------------------------------------------------
extern UINT *____KERNELSTART;
extern UINT *____KERNELEND;
//----------------------------------------------------------------------------------
/**
* \var PhysicalKernelStart
* \brief Physical start address of the kernel memory
*/
extern UINT PhysicalKernelStart;
/**
* \var PhysicalKernelEnd
* \brief Physical end address of the kernel memory
*/
extern UINT PhysicalKernelEnd;
/**
* \var PhysicalManagedInfoStart
* \brief Physical start address of the physical information memory
*/
extern UINT PhysicalManagedInfoStart;
/**
* \var PhysicalManagedInfoEnd
* \brief Physical end address of the physical information memory
*/
extern UINT PhysicalManagedInfoEnd;
/**
* \var PhysicalSuperMapStart
* \brief Physical start address of the super map
*/
extern UINT PhysicalSuperMapStart;
/**
* \var PhysicalSuperMapSize
* \brief Size of the super map in 4 bytes
*/
extern UINT PhysicalSuperMapSize;
/**
* \var PhysicalMapsStart
* \brief Physical start address of the maps
*/
extern UINT PhysicalMapsStart;
/**
* \var PhysicalMapsCount
* \brief Number of the maps
*/
extern UINT PhysicalMapsCount;
/**
* \var PhysicalMapSize
* \brief Size of a single map in 4 bytes
*/
extern UINT PhysicalMapSize;
/**
* \fn void_free_frame(UINT Frame)
* \brief Internal function to mark the given frame as free
*/
extern void _free_frame(UINT Frame);
/**
* \fn void _use_frame(UINT Frame)
* \brief Internal function to mark the given frame as used
*/
extern void _use_frame(UINT Frame);
/**
* \fn void _use_frames(UINT Start, UINT Count)
* \brief Internal function to mark the given frame and Count-1 frames after as used
*/
extern void _use_frames(UINT Start, UINT Count);
/**
* \fn UINT8 _check_frame(UINT Frame)
* \brief Internal function to check whether a frame is marked as used or not
*/
extern UINT8 _check_frame(UINT Frame);
// .... HIER KOMMT EIGENTLICH NOCH MEHRKann ich die Kommentare auch auslagern?
Hätte das einen Sinn?
Sind die Kommentare vielleicht einfach besser in der Source-Datei aufgehoben?
Dann: Ist es sinnvoll Dateien zu kommentieren? Wenn ja, wann und warum?
Außerdem: Was hat es mit diesen defgroups auf sich? Wie verwendet man sie? Wofür verwendet man sie? Gibt es andere Möglichkeiten, die Dokumentation zu strukturieren?
Ich hoffe ihr könnt mir ein paar dieser Fragen beantworten.
Wenn genügend Antworten kommen könnten wir das fürs Wiki zusammenfassen
