[poppler] Patch: Some documentation

[Albert Astals Cid]

El Dimecres, 18 de juliol de 2012, a les 11:58:49, cheshirekow va escriure:
> 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 ///).

Ok, it's fine, let's convert all the // to ///

But your patch can't be commited yet, as far as i remember it has some things 
like "i think this does bla bla", which can't go it :D

Can you create a bug in the bugzilla and attach the patch so we use the 
comment feature over patches there?

Cheers,
  Albert

> 
> _______________________________________________
> poppler mailing list
> poppler at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/poppler