Single-to-noise ratio. You can put it in there, but I probably won't read it. I basically assume that all javadoc/doxygen-style summary/@param/@return-style do

Single-to-noise ratio. You can put it in there, but I probably won't read it. I basically assume that all javadoc/doxygen-style summary/@param/@return-style docs are entirely noise. I much prefer the "docstring" style comments, especially though in Clojure, or Python. Examples... Clojure: user=> (doc map) ------------------------- clojure.core/map ([f coll] [f c1 c2] [f c1 c2 c3] [f c1 c2 c3 & colls]) Returns a lazy sequence consisting of the result of applying f to the set of first items of each coll, followed by applying f to the set of second items in each coll, until any one of the colls is exhausted. Any remaining items in other colls are ignored. Function f should accept number-of-colls arguments. Python: Help on built-in function map in module __builtin__: map(...) map(function, sequence[, sequence, ...]) -> list Return a list of the results of applying the function to the items of the argument sequence(s). If more than one sequence is given, the function is called with an argument list consisting of the corresponding item of each sequence, substituting None for missing values when not all sequences have the same length. If the function is None, return a list of the items of the sequence (or a list of tuples if more than one sequence). And on the far other end of the spectrum, here's some C# / MSDN docs: Syntax public static IEnumerable<TResult> Select<TSource, TResult>( this IEnumerable<TSource> source, Func<TSource, TResult> selector ) Type Parameters TSource The type of the elements of source. TResult The type of the value returned by selector. Parameters source Type: System.Collections.Generic.IEnumerable<TSource> A sequence of values to invoke a transform function on. selector Type: System.Func<TSource, TResult> A transform function to apply to each element. Return Value Type: System.Collections.Generic.IEnumerable<TResult> An IEnumerable<T> whose elements are the result of invoking the transform function on each element of source. Usage Note In Visual Basic and C#, you can call this method as an instance method on any object of type IEnumerable<TSource>. When you use instance method syntax to call this method, omit the first parameter. For more information, see Extension Methods (Visual Basic) or Extension Methods (C# Programming Guide). Entertainingly, this is only one of many overloads in the C# version. The Clojure and Python functions are variadic with parallel traversal of collections. Those languages spend their precious docs space covering the corner cases.