Jose Fonseca wrote:
>
> On Fri, 2002-01-25 at 03:11, Jens Owen wrote:
> > José Fonseca wrote:
> >
> > > Unless anyone has a better suggestion I think this is the way to go. What
> > > do the "elder" developers think?
> >
> > The one down side I see is the complexity (and clutter) created by the
> > TAGS. I like simple
> > paragraphs myself. Perhaps we could encourage a very basic simple
> > template for most things, so the comments are still easy to read and
> > maintain when editing the code itself.
> >
> > -- /\
> > Jens Owen / \/\ _
> > [EMAIL PROTECTED] / \ \ \ Steamboat Springs, Colorado
>
> The tags are quite transparent and they are only used in the functions
> descriptions. As in:
>
> /**
> * Used to open the main /dev/drm
> * control device. If running as root, this device is
> * automatically created in /dev with the appropriate
> * mode.
> *
> * \note This function replaces drmOpenDRM in the old DRI
> * documentation.
> *
> * \returns a file descriptor for the main /dev/drm
> * control device, or a negative value on error.
> */
>
> static int drmOpenDevice(long dev, int minor)
> {
> ...
>
> There is no point in putting tags inside a function body because (at
> least) Doxygen doesn't document a function inner working.
Jose,
The example you give looks reasonable, but here is another example, for
drmAddMap, that I find much harder to read:
/**
* Specifies a range of memory that is available for mapping by a
* non-root process using mmap(2) on /dev/drm?.
*
* \returns 0 on success and a negative value on error.
*
* The handle will be set to a value that may be used as the
* <CODE>offset</CODE> parameter for <CODE>mmap(2)</CODE>. May only
* be called by <CODE>root</CODE>.
*
* <H3>Mapping the frame buffer </H3>
*
* <P>For the frame buffer, <UL> <LI> <CODE>offset</CODE> will be the
* physical address of the start of the frame buffer,</LI> <LI>
* <CODE>size</CODE> will be the size of the frame buffer in bytes,
* and </LI> <LI> <CODE>type</CODE> will be
* <CODE>::DRM_FRAME_BUFFER</CODE>.</LI> </UL> <P>The area mapped will
* be uncached. If MTRR support is available in the kernel, the frame
* buffer area will be set to write combining.
*
* <H3>Mapping the MMIO register area </H3>
*
* <P>For the MMIO register area, <UL> <LI> <CODE>offset</CODE> will
* be the physical address of the start of the register area,</LI>
* <LI> <CODE>size</CODE> will be the size of the register area bytes,
* and </LI> <LI> <CODE>type</CODE> will be
* <CODE>::DRM_REGISTERS</CODE>.</LI> </UL> <P>The area mapped will be
* uncached. <P>
*
* <H3>Mapping the SAREA </H3>
*
* <P>The SAREA is a shared memory segment that is used for
* communication between the X server, the direct-rendering clients,
* and the kernel. Standard <CODE>shm*</CODE> calls provide only
* uid/gid-based access restrictions and do not provide the ability
* to enforce the DRI's security policy, so this area is created and
* mapped via the DRM interface. <P>For the SAREA, <UL> <LI>
* <CODE>offset</CODE> will be ignored and should be set to zero,
* </LI> <LI> <CODE>size</CODE> will be the desired size of the SAREA
* in bytes,</LI> <LI> <CODE>type</CODE> will be
* <CODE>DRM_SHM</CODE>.</LI> </UL> <P>A shared memory area of the
* requested size will be created and locked in kernel memory. This
* area may be mapped into client-space by using the
* <CODE>handle</CODE> returned.
*
* <P> <H3>Flags </H3>
*
* <P>Several flags are provided to modify the actions of
* <CODE>drmAddMap()</CODE>:
*
* <UL> <LI><CODE>::DRM_RESTRICT</CODE> will prevent the area from
* being mapped into client space by a non-<CODE>root</CODE> user.
* The area will still be mapped into kernel-space, so this is useful
* to allow the kernel to have access to registers that control DMA
* while preventing the client from having such access.</LI>
*
* <LI><CODE>::DRM_READ_ONLY</CODE> will force the area to be mapped as
* a read-only region in client space. This is useful if the client
* requires read access to registers that are in an area that also
* contains, for example, DMA control registers. (The client must not
* be allowed to initiate DMA to arbitrary locations in memory, since
* this opens up a significant security risk [FM99]).</LI>
*
* <LI><CODE>::DRM_LOCKED</CODE> will force SAREA pages (of
* <CODE>type</CODE> <CODE>::DRM_SHM</CODE>) to be locked into kernel
* memory. This flag will be ignored for the SI, since all shared
* memory will be locked.</LI> <LI><CODE>::DRM_KERNEL</CODE> will
* require that the kernel has access to the mapped region. This flag
* will be ignored in the SI and the kernel will have read/write
* access to all mapped regions.</LI>
*
* <LI><CODE>::DRM_WRITE_COMBINING</CODE> will specify that, if
* possible, the mapped region will be set to write-combining. (This
* is the default for <CODE>::DRM_FRAME_BUFFER</CODE> but may be useful
* on some (non-PC-class) hardware for
* <CODE>::DRM_REGISTERS</CODE>.)</LI>
*
* <LI><CODE>::DRM_CONTAINS_LOCK</CODE> will specify that this SAREA
* region (of <CODE>type</CODE> <CODE>::DRM_SHM</CODE>) contains the
* hardware lock at the beginning of the region. This flag must be
* specified for one of the SAREA regions.</LI> </UL>
*/
> In fact a perhaps better alternative would be document only the headers
> files instead of the implementation so that the code remains lean. (The
> downside would be bigger include fields and more C preprocessing time
> but the includes files are just used inside XFree86 tree and the
> difference in the build time would be almost negligible.)
That would be a reasonable compromise.
-- /\
Jens Owen / \/\ _
[EMAIL PROTECTED] / \ \ \ Steamboat Springs, Colorado
_______________________________________________
Dri-devel mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/dri-devel
