From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 02 Dec 2010 19:30:10 GMT
Subject: Re: [RFC/PATCH] Git.pm: discourage casual use
Message-ID: <7veia0q8fx.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20101202190546.GI3962@burratino>

Jonathan Nieder <jrnieder@gmail.com> writes:

> So how about something like this patch, to start?

Ok.  We may probably want to reduce the repetition of "easy", though.

> diff --git a/perl/Git.pm b/perl/Git.pm
> index 6cb0dd1..7f6c500 100644
> --- a/perl/Git.pm
> +++ b/perl/Git.pm
> @@ -63,12 +63,16 @@ require Exporter;
>  
>  =head1 DESCRIPTION
>  
> -This module provides Perl scripts easy way to interface the Git version control
> -system. The modules have an easy and well-tested way to call arbitrary Git
> +This module provides an easy way to interact with the Git version control
> +system for Git's internal perl scripts.
> +The modules have an easy and well-tested way to call arbitrary Git
>  commands; in the future, the interface will also provide specialized methods
>  for doing easily operations which are not totally trivial to do over
>  the generic command interface.
>  
> +Note: this module should not be used by code outside the Git package itself,
> +since the API is not stable yet.
> +
>  While some commands can be executed outside of any context (e.g. 'version'
>  or 'init'), most operations require a repository context, which in practice
>  means getting an instance of the Git object using the repository() constructor.