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 <[email protected]> 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 > [email protected] > http://lists.freedesktop.org/mailman/listinfo/poppler _______________________________________________ poppler mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/poppler
