Hi all, Just letting you know that after 0.10.11 I'll probably put a strict requirement on doxygen usage on every new function. There reasons for this: - it's hard to figure out what any given function does, having comments at least means you can quickly figure out what a function should do. - having documented what a function _should_ do makes it easy to find discrepancies with what the function actually does. - strict parameter labelling for in|out etc. and documentation of return values makes it easier to write tests for and again find bugs. - the light blue colour of comments is soothing to the soul, quite unlike the hard black of code or the stinging red of strings.
doxygen style is javascript style with autobrief (first sentence is summary). /** * This function does something important. Blah blah foo blah bar * blah blah... * * @param a[in] Some value deciding foo * @param p[out] Set to the current address of bar. * @return Zero if foo or non-zero otherwise. */ int foo(int a, char *p) As with everything, there will be exceptions, relaxed rules, etc. based on common sense but not very many. If anyone has any better suggestions than doxygen, let me know. (This isn't meant as a contest of "my favourite commenting system", it has to be clearly superiour to doxygen) Cheers, Peter ------------------------------------------------------------------------------ The ultimate all-in-one performance toolkit: Intel(R) Parallel Studio XE: Pinpoint memory and threading errors before they happen. Find and fix more than 250 security defects in the development cycle. Locate bottlenecks in serial and parallel code that limit performance. http://p.sf.net/sfu/intel-dev2devfeb _______________________________________________ Linuxwacom-devel mailing list Linuxwacom-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/linuxwacom-devel
