I often find  when trying to read buildlink files, particularly those
that can choose which pkg to use, that it is hard to figure out what
the intent is in terms of the policy of what to choose when.

Examples:

  mk/krb5.buildlink3.mk: does not note explicitly that in-tree heimdal
  is not ok, and whether that is because it is really not ok or
  because the buildlink file has not yet been enhanced to allow it.

  fonts/fontconfig/buildlink3.mk: the policy and reason for whether to
  use the XFree86-provided fontconfig or require pkgsrc is not clear.

I don't mean comments that explain how the buildlink rules implement
the policy, but a concise description of what the intended behavior
is, so that a user of the buildlink file (package writer) can
understand the required variable settings without having to understand
the implementation of the buildlink file (something along the lines
of Eiffel's design by contract).

I don't mean to gripe; this whole framework makes things work more
smoothly.  It can be just a bit hard to follow for one who is not a
buildlink guru.

-- 
        Greg Troxel <gdt@ir.bbn.com>