FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor


 
 
LinkBack Thread Tools
 
Old 04-15-2008, 12:16 PM
Sebastian Nowicki
 
Default libalpm documentation

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

_______________________________________________
pacman-dev mailing list
pacman-dev@archlinux.org
http://archlinux.org/mailman/listinfo/pacman-dev
 
Old 04-15-2008, 02:46 PM
Sebastian Nowicki
 
Default libalpm documentation

Sorry, I don't know what I was looking at, but looking at the
generated doxygen documentation now a lot of things _are_ documented.
Too bad you can't delete emails. I'm going to shut my mouth and go
read it now. Feel free to ignore the previous email.

_______________________________________________
pacman-dev mailing list
pacman-dev@archlinux.org
http://archlinux.org/mailman/listinfo/pacman-dev
 
Old 04-15-2008, 02:55 PM
Nagy Gabor
 
Default libalpm documentation

> Sorry, I don't know what I was looking at, but looking at the
> generated doxygen documentation now a lot of things _are_ documented.
> Too bad you can't delete emails. I'm going to shut my mouth and go
> read it now. Feel free to ignore the previous email.

No problem, I agree that our documentation is far from perfect. I always suggest
looking into pacman (front-end) code, because it is quite simple and working
implementation of our back-end.

Bye


----------------------------------------------------
SZTE Egyetemi Könyvtár - http://www.bibl.u-szeged.hu
This mail sent through IMP: http://horde.org/imp/


_______________________________________________
pacman-dev mailing list
pacman-dev@archlinux.org
http://archlinux.org/mailman/listinfo/pacman-dev
 

Thread Tools




All times are GMT. The time now is 05:36 AM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright ©2007 - 2008, www.linux-archive.org