On 6 July 2012 14:41, Andreas Färber <afaer...@suse.de> wrote: > Small improvement would be to replace "Returns the" with "Returns: The" > in line with how you annotated the arguments, and the function summary > should go into its own paragraph between @foo: and Returns:. > > http://developer.gnome.org/gtk-doc-manual/unstable/documenting_symbols.html.en
Hmm. I was just following the existing practice in this file, which consistently uses "Returns $whatever" without a colon. memory.h uses "Returns $whatever" rather than "Returns: $whatever" too. But I guess the doc you link to is the official statement of the required syntax. How are these comments? /** * extract32: * @value: the value to extract the bit field from * @start: the lowest bit in the bit field (numbered from 0) * @length: the length of the bit field * * Extract from the 32 bit input @value the bit field specified by the * @start and @length parameters, and return it. The bit field must * lie entirely within the 32 bit word. It is valid to request that * all 32 bits are returned (ie @length 32 and @start 0). * * Returns: the value of the bit field extracted from the input value. */ /** * extract64: * @value: the value to extract the bit field from * @start: the lowest bit in the bit field (numbered from 0) * @length: the length of the bit field * * Extract from the 64 bit input @value the bit field specified by the * @start and @length parameters, and return it. The bit field must * lie entirely within the 64 bit word. It is valid to request that * all 64 bits are returned (ie @length 64 and @start 0). * * Returns: the value of the bit field extracted from the input value. */ /** * deposit32: * @value: initial value to insert bit field into * @start: the lowest bit in the bit field (numbered from 0) * @length: the length of the bit field * @fieldval: the value to insert into the bit field * * Deposit @fieldval into the 32 bit @value at the bit field specified * by the @start and @length parameters, and return the modified * @value. Bits of @value outside the bit field are not modified. * Bits of @fieldval above the least significant @length bits are * ignored. The bit field must lie entirely within the 32 bit word. * It is valid to request that all 64 bits are modified (ie @length * 64 and @start 0). * * Returns: the modified @value. */ /** * deposit32: * @value: initial value to insert bit field into * @start: the lowest bit in the bit field (numbered from 0) * @length: the length of the bit field * @fieldval: the value to insert into the bit field * * Deposit @fieldval into the 64 bit @value at the bit field specified * by the @start and @length parameters, and return the modified * @value. Bits of @value outside the bit field are not modified. * Bits of @fieldval above the least significant @length bits are * ignored. The bit field must lie entirely within the 32 bit word. * It is valid to request that all 64 bits are modified (ie @length * 64 and @start 0). * * Returns: the modified @value. */ -- PMM
