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

Go Back   Linux Archive > ArchLinux > ArchLinux Pacman Development

 
 
LinkBack Thread Tools
 
Old 02-27-2011, 06:29 PM
Dan McGee
 
Default Document API changes for pacman-3.5 release

On Sun, Feb 27, 2011 at 7:35 AM, Allan McRae <allan@archlinux.org> wrote:
> Signed-off-by: Allan McRae <allan@archlinux.org>
> ---
> *README | * 36 ++++++++++++++++++++++++++++++++++++
> *1 files changed, 36 insertions(+), 0 deletions(-)
>
> diff --git a/README b/README
> index 1276eaa..5da572f 100644
> --- a/README
> +++ b/README
> @@ -328,3 +328,39 @@ API CHANGES BETWEEN 3.3 AND 3.4
> *- alpm_pkg_unused_deltas()
> *- alpm_conflict_get_reason()
> *- error code: PM_ERR_PKG_INVALID_ARCH
> +
> +
> +API CHANGES BETWEEN 3.4 AND 3.5
> +===============================
> +
> +[REMOVED]
> +- alpm_db_register_local()
> +- alpm_pkg_has_force()
> +- alpm_depcmp()
> +
> +[CHANGED]
> +- alpm_trans_cb_progress type had some types changed from int to size_t
- alpm_cb_log format string is now const char *

> +- the interface to add/remove targets:
> + *- functions take pmpkg_t * rather than char *.
> + *- alpm_sync_target() and alpm_sync_dbtarget() are replaced by alpm_add_pkg()
> + *- alpm_add_target() is replaced by alpm_add_pkg()
> + *- alpm_remove_target() is replaced by alpm_remove_pkg()
> + *- packages can come from:
> + * * - alpm_db_get_pkg() for normal targets
> + * * - alpm_find_dbs_satisfier() for versioned provisions
> + * * - alpm_find_grp_pkgs() for groups
> +- alpm_deptest() is replaced by the more flexibile alpm_find_satisfier()
> +- size_t used for alpm_list_t sizes
> + *- return type for alpm_list_count()
> + *- parameter type in alpm_list_msort() and alpm_list_nth()
> +
> +[ADDED]
> +- alpm_option_get_checkspace(), alpm_option_set_checkspace()
> +- alpm_find_grp_pkgs()
> +- alpm_trans_get_flags()
> +- error codes:
> + * PM_ERR_DISK_SPACE, PM_ERR_WRITE
> +- flags
> + * PM_TRANS_FLAG_NODEPVERSION, PM_TRANS_EVT_DISKSPACE_START,
> + * PM_TRANS_EVT_DISKSPACE_DONE, PM_TRANS_CONV_SELECT_PROVIDER,
> + * PM_TRANS_PROGRESS_DISKSPACE_START, PM_TRANS_PROGRESS_INTEGRITY_START
> --
> 1.7.4.1
>
>
>
 
Old 02-28-2011, 09:02 PM
Rémy Oudompheng
 
Default Document API changes for pacman-3.5 release

Would you approve documenting in alpm.h the type of elements in lists
returned by libalpm functions ? They do not look obvious at all for
someone that is not familiar with the internals of libalpm.

--
Rémy.
 
Old 02-28-2011, 09:04 PM
Dan McGee
 
Default Document API changes for pacman-3.5 release

On Mon, Feb 28, 2011 at 4:02 PM, Rémy Oudompheng
<remyoudompheng@gmail.com> wrote:
> Would you approve documenting in alpm.h the type of elements in lists
> returned by libalpm functions ? They do not look obvious at all for
> someone that is not familiar with the internals of libalpm.

Definitely. If you can do it in Doxygen style that would be a step in
the right direction too, since we could eventually get autogenerated
docs and manpages, but baby steps.

-Dan
 
Old 03-01-2011, 06:25 AM
Rémy Oudompheng
 
Default Document API changes for pacman-3.5 release

On 2011/2/28 Dan McGee <dpmcgee@gmail.com> wrote:
> On Mon, Feb 28, 2011 at 4:02 PM, Rémy Oudompheng
> <remyoudompheng@gmail.com> wrote:
>> Would you approve documenting in alpm.h the type of elements in lists
>> returned by libalpm functions ? They do not look obvious at all for
>> someone that is not familiar with the internals of libalpm.
>
> Definitely. If you can do it in Doxygen style that would be a step in
> the right direction too, since we could eventually get autogenerated
> docs and manpages, but baby steps.

Do we want to put any documentation in alpm.h or would it better to
have Doxygen style only in the source code, documenting the public API
?

I hesitate between two approaches : I see a use of Doxygen groups
(with the @addtogroup command) but sometimes, it seems very natural to
use an object-oriented style. For example, we could document
alpm_pkg_get_depends() as

/**
* Returns a reference to the list of package dependencies.
* @public @memberof pmpkg_t
* @return a pointer to a list of pmdepend_t structures.
*/
alpm_list_t *alpm_pkg_get_depends(pmpkg_t *pkg);

So that it shows on a page dedicated to pmpkg_t.

--
Rémy.
 
Old 03-01-2011, 12:17 PM
Dan McGee
 
Default Document API changes for pacman-3.5 release

On Tue, Mar 1, 2011 at 1:25 AM, Rémy Oudompheng
<remyoudompheng@gmail.com> wrote:
> On 2011/2/28 Dan McGee <dpmcgee@gmail.com> wrote:
>> On Mon, Feb 28, 2011 at 4:02 PM, Rémy Oudompheng
>> <remyoudompheng@gmail.com> wrote:
>>> Would you approve documenting in alpm.h the type of elements in lists
>>> returned by libalpm functions ? They do not look obvious at all for
>>> someone that is not familiar with the internals of libalpm.
>>
>> Definitely. If you can do it in Doxygen style that would be a step in
>> the right direction too, since we could eventually get autogenerated
>> docs and manpages, but baby steps.
>
> Do we want to put any documentation in alpm.h or would it better to
> have Doxygen style only in the source code, documenting the public API
> ?
Both? And maybe doxygen doesn't belong in alpm.h, but it surely
deserves some more documentation than it has. Compare our header to
something more carefully constructed such as /usr/include/archive.h.

> I hesitate between two approaches : I see a use of Doxygen groups
> (with the @addtogroup command) but sometimes, it seems very natural to
> use an object-oriented style. For example, we could document
> alpm_pkg_get_depends() as
>
> /**
> ** Returns a reference to the list of package dependencies.
> ** @public @memberof pmpkg_t
> ** @return a pointer to a list of pmdepend_t structures.
> **/
> alpm_list_t *alpm_pkg_get_depends(pmpkg_t *pkg);
>
> So that it shows on a page dedicated to pmpkg_t.

I'll tell you what- you present an approach that works once you've
documented enough things- I think the question will answer itself
better then and I'm more than happy to let the person that does the
work bake the cake on this decision.

-Dan
 

Thread Tools




All times are GMT. The time now is 09:27 AM.

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