Decide on function documentation syntax

[gilligan]

What should our comment format for function documentation look like ?

Here are some current examples:

  /* Recursively collect sets that verify a given predicate named `pred'
     from the set `attrs'.  The recursion is stopped when the predicate is
     verified.
{} ->
     Type:
       collect ::
         (AttrSet -> Bool) -> AttrSet -> [x]

     Example:
       collect isList { a = { b = ["b"]; }; c = [1]; }
       => [["b"] [1]]

       collect (x: x ? outPath)
          { a = { outPath = "a/"; }; b = { outPath = "b/"; }; }
       => [{ outPath = "a/"; } { outPath = "b/"; }]
  */
  collect = pred: attrs:

  /* Utility function that creates a {name, value} pair as expected by
     builtins.listToAttrs.

     Example:
       nameValuePair "some" 6
       => { name = "some"; value = 6; }
  */
  nameValuePair = name: value: { inherit name value; };

  /* Return an attribute from nested attribute sets.

     Example:
       x = { a = { b = 3; }; }
       attrByPath ["a" "b"] 6 x
       => 3
       attrByPath ["z" "z"] 6 x
       => 6
  */
  attrByPath = attrPath: default: e:

Up for debate:

• Haskell'ish type signatures ? -- NO
• Examples ? (how many?)
• describe arguments ?

[gilligan]

So we agreed to NOT add type signatures to the documentation:

They are not useful for everyone, it is hard to make them consistent, if we add proper examples those have more value to everyone instead of having inconsistent signatures that are only useful for some people anyway.

[gilligan]

Concerning examples:

Whenever feasible which should try to provide 2 examples. Especially in case of higher order functions. We'll just have to use common sense to figure out cases where multiple cases would just seem redundant ;)