[poppler] Patch: Some documentation

[cheshirekow]

On Mon, 2012-07-16 at 23:35 +0200, Ihar `Philips` Filipau wrote:
> 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 :)

I agree with that. As someone who is trying to understand the internal
workings of the library, I would appreciate the ability to navigate the
source code and documentation in the doxygen generated output.

As a note, it seems to me that the internals and the public facing API
are located in separate subdirectories of the source tree. Therefore,
the default doxygen configuration included in the library can easily
exclude (or rather, simply not include) those subdirectories that are
not part of the public facing API. A separate doxygen configuration for
the internals can be used to generate a second set of documentation for
those who are interested in learning the internals (like me). 

So... if changing // --> /// causes a lot of problems for maintenance I
understand why it may be undesirable. Otherwise, I would encourage that
doc-comments be used wherever they have meaningful information, to avoid
having to browse sourcecode unassisted by doxygen in order to find this
information. Unfortunately, to the best of my knowledge, it isn't
possible to tell doxygen to extract "normal" comments as doc-comments
(i.e. to treat // as ///).