|
From: Bart V. A. <bva...@ac...> - 2015-04-22 10:20:10
|
On 04/21/15 23:02, Philippe Waroquiers wrote: > On Mon, 2015-04-20 at 23:46 +0200, Florian Krohm wrote: >> On 20.04.2015 23:28, Philippe Waroquiers wrote: >>> Nice cleanup. >>> One small comment: wouldn't the description of VG_(sr_as_string)() >>> better be put in the .h rather than in the .c file ? >>> The fact that the memory is static (or must be freed by the caller) >>> is better described there ? >> >> I tend to favour small comments in header files and put noteworthy >> details next to the implementation. But I have no strong feelings and we >> don't have a policy for this either. So if you want to change it please >> feel free. > Done as revision 15127. > > At work, we have a convention/guideline that to know how to use a > module, it is/should be sufficient to read the 'spec' (i.e. the .h) > of the module. > This allows to limit the reading to what is needed. > E.g. allows to skip internal functions/comments/internal data structures > and so on. > > So, information for the caller such as > 'you must free the returned pointer' > or > 'returns a static buffer, overwritten on next invocation' > is better placed in the .h, following this convention. > > I think many modules of Valgrind already follows > this approach. > > Maybe we could be more systematic in that approach ? There might be good reasons to add documentation for Valgrind functions in Valgrind header files. But I think it's worth mentioning here that there is a strict policy in the Linux kernel is to add such documentation in the .c files only. The rationale behind this policy is that it is easy to forget to update a header file when modifying the implementation. That's why in the Linux kernel the documentation is kept close to the implementation. Bart. |