dir: add commentary explaining match_pathspec_item's return value

dir: add commentary explaining match_pathspec_item's return value

The way match_pathspec_item() handles names and pathspecs with trailing
slash characters, in conjunction with special options like
DO_MATCH_DIRECTORY and DO_MATCH_LEADING_PATHSPEC were non-obvious, and
broken until this patch series.  Add a table in a comment explaining the
intent of how these work.

Signed-off-by: Elijah Newren <redacted>
Signed-off-by: Junio C Hamano <redacted>