archive/OpenAFSDoxygenStyleGuide.mdwn

   1 NOTE: This is a work in progress.
   2
   3 An example doxygen comment,
   4
   5     /*!
   6      * find the first occurrence of a volume header file and return the path.
   7      *
   8      * \param[out] ec          outbound error code
   9      * \param[in]  volumeId    volume id to find
  10      * \param[out] partitionp  pointer to disk partition path string
  11      * \param[out] namep       pointer to volume header file name string
  12      *
  13      * \post path to first occurrence of volume header is returned in partitionp
  14      *       and namep, or ec is set accordingly.
  15      *
  16      * \warning this function is NOT re-entrant -- partitionp and namep point to
  17      *          static data segments
  18      *
  19      * \note if a volume utility inadvertently leaves behind a stale volume header
  20      *       on a vice partition, it is possible for callers to get the wrong one,
  21      *       depending on the order of the disk partition linked list.
  22      *
  23      */
  24     void
  25     VGetVolumePath(Error * ec, VolId volumeId, char **partitionp, char **namep)
  26
  27 -- Michael Meffie - 10 Oct 2008