[pacman-dev] libalpm documentation

[Sebastian Nowicki]

It seems that libalpm is heavily undocumented. I was wondering if  
anyone is currently working on doxygen comments? Glancing over the  
code it seems in a few places there are comments for functions, but  
they aren't doxygen comments. They may not have in depth detail about  
the function, or describe how to use that function, but they do have a  
description, and that's better than nothing.

I think a library should be useable by looking at only the  
documentation. With more clients springing up since libalpm came out,  
I think documentation should be a high priority. For me, libalpm is  
currently completely confusing and I have no idea how the functions  
and structs, etc., come together, so unfortunately without a lot of  
reading I won't be able to contribute much to the documentation. It is  
also difficult to actually use libalpm without reading through the code.

While searching for any information about this I did find the bug  
(#9237 [1]) on flyspray, as well as the thread "Libalpm direction and  
usage by others" [2], but that seemed a bit more about the design of  
the API.

Having reading that thread I think it might be worth saying that I am  
planning on creating an Objective-C wrapper for libalpm, as well as a  
front-end in Objective-C/Cocoa for Mac OS X. I don't know how that  
will turn out and it's mostly an idea, so I don't want to make any  
empty promises. Good documentation would definitely help me to do  
that, but unfortunately the documentation is not that great. If I do  
stick with the project I will most likely be going through the code  
and, once I understand it, documenting it. I think that the  
documentation could get to a decent state if developers progressively  
commented the functions and structs, etc., while changing the code.  
Taking a minute or two to just write a brief description would be  
great. Other developers could also later take a few seconds to  
document the parameters, then someone else could write up the details,  
etc. I saw a patch set yesterday that refactored code and it had  
doxygen comments for the new functions, which was great.

[1] http://bugs.archlinux.org/index.php?do=details&task_id=9237
[2] http://archlinux.org/pipermail/pacman-dev/2008-March/011517.html