[poppler] Patch: Some documentation

[Ihar `Philips` Filipau]

On 7/16/12, Albert Astals Cid <aacid at kde.org> wrote:
>>
>> More documentation is better. Anything that helps understanding what
>> the hell is going on inside, is good.
>
> Sure, but you're not answering my question ;-)
>

Oops. Sorry. I thought you were objecting to the description of the
PDF sacred secret: difference between the media/crop/trim/bleed/etc
boxes. :)

Elevating some comments to the level of doc-comment happens often and
quite normal practice. There are lots of doc-comment-like comments in
the code - converting them to real doc-comments is an overdue
correction. (*)

The only potential discussion I see, is whether that makes merges with
the xpdf harder or not. Such modifications occasionally cause huge
merge conflicts. For that, you are the authority :)

(*) On many projects adding a doc-comment-like comment is actually an
error. If comment reads and looks like a doc-comment, then it should
be formatted as such.