[poppler] Patch: Some documentation

[Albert Astals Cid]

Hi,

El Dimarts, 10 de juliol de 2012, a les 16:42:47, cheshirekow va escriure:
> As I've been trying to learn the API I've been adding doxygen style
> comments my own git branch. I'm not sure if all my comments are correct
> but it has helped me keep track of what I've figured out thus far, and
> perhaps may be useful to others.
> 
> I've attached a patch of my changes. I believe I've only touched comment
> lines, except for one or two class member lists which were commented (I
> added ///< so that doxygen picks up those comments too).
> 
> I haven't documented a lot, just some comments here and there on some of
> the main components (I think). Feel free to use or throw away, as you
> please. I will likely continue to add comments until I get more
> comfortable with the library, so if such contributions appear to be
> useful, let me know and I will continue to submit my documentation.

To be honest i'm not sure 

-  // Retuns the entry that belongs to the offset
+  /// Returns the entry that belongs to the offset

really add value, i know it is doxygen syntax, but to be honest we do *not* 
want people to use poppler core internals, so documentation of functions 
should be for internal consumption only thus the need for doxygen-like syntax 
is small in my opinion.

What do others think?

Albert

> 
> -Josh