root/traduc/branches/bv747/manuel/ref/comment.sgml

<!--
$Header: /var/lib/cvs/pgsql-fr/sgml/ref/comment.sgml,v 1.7 2004/12/21 23:09:12 guillaume Exp $
PostgreSQL documentation
-->

<refentry id="SQL-COMMENT">
 <refmeta>
  <refentrytitle id="SQL-COMMENT-TITLE">COMMENT</refentrytitle>
  <refmiscinfo>SQL - Instructions du langage</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>COMMENT</refname>
  <refpurpose>définit ou modifie le commentaire sur un objet</refpurpose>
 </refnamediv>

 <indexterm zone="sql-comment">
  <primary>COMMENT</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
COMMENT ON
{
  TABLE <replaceable class="PARAMETER">nom_objet</replaceable> |
  COLUMN <replaceable class="PARAMETER">nom_table</replaceable>.<replaceable
class="PARAMETER">nom_colonne</replaceable> |
  AGGREGATE <replaceable class="PARAMETER">nom_agrégat</replaceable>
(<replaceable class="PARAMETER">type_agrégat</replaceable>) |
  CONSTRAINT <replaceable class="PARAMETER">nom_contrainte</replaceable> ON
<replaceable class="PARAMETER">nom_table</replaceable> |
  DATABASE <replaceable class="PARAMETER">nom_objet</replaceable> |
  DOMAIN <replaceable class="PARAMETER">nom_objet</replaceable> |
  FUNCTION <replaceable class="PARAMETER">nom_fonction</replaceable>
(<replaceable class="PARAMETER">type_arg1</replaceable>, <replaceable
class="PARAMETER">type_arg2</replaceable>, ...) |
  INDEX <replaceable class="PARAMETER">nom_objet</replaceable> |
  OPERATOR <replaceable class="PARAMETER">op</replaceable> (<replaceable
class="PARAMETER">type_operande1</replaceable>, <replaceable
class="PARAMETER">type_operande2</replaceable>) |
  RULE <replaceable class="PARAMETER">nom_role</replaceable> ON <replaceable
class="PARAMETER">nom_table</replaceable> |
  SCHEMA <replaceable class="PARAMETER">nom_objet</replaceable> |
  SEQUENCE <replaceable class="PARAMETER">nom_objet</replaceable> |
  TRIGGER <replaceable class="PARAMETER">nom_declencheur</replaceable> ON
<replaceable class="PARAMETER">nom_table</replaceable> |
  TYPE <replaceable class="PARAMETER">nom_objet</replaceable> |
  VIEW <replaceable class="PARAMETER">nom_objet</replaceable>
} IS <replaceable class="PARAMETER">'texte'</replaceable>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>COMMENT</command> stocke un commentaire sur un objet de base de
    données. Les commentaires peuvent être facilement récupérés avec les
    commandes de <application>psql</application> <command>\dd</command>,
    <command>\d+</command> et <command>\l+</command>. Les autres interfaces
    utilisateur permettant de récupérer les commentaires peuvent être
    construites au-dessus des même fonctions intégrées que celles utilisées par
    <application>psql</application>, nommément <function>obj_description</> et
    <function>col_description</>.
  </para>

  <para>
    Pour modifier un commentaire, lancez une nouvelle commande
    <command>COMMENT</> pour le même objet. Seule une chaîne de commentaire est
    stockée pour chaque objet. Pour supprimer un commentaire, écrivez
    <literal>NULL</literal> à la place de la chaîne de texte. Les commentaires
    sont automatiquement supprimés lorsque l'objet est supprimé.
  </para>
 </refsect1>

 <refsect1>
  <title>Paramètres</title>

  <variablelist>
   <varlistentry>
    <term><replaceable class="parameter">nom_objet</replaceable></term>
    <term><replaceable
     class="parameter">nom_table.nom_colonne</replaceable></term>
    <term><replaceable class="parameter">nom_agregat</replaceable></term>
    <term><replaceable class="parameter">nom_contrainte</replaceable></term>
    <term><replaceable class="parameter">nom_fonction</replaceable></term>
    <term><replaceable class="parameter">op</replaceable></term>
    <term><replaceable class="parameter">nom_regle</replaceable></term>
    <term><replaceable class="parameter">nom_declencheur</replaceable></term>
    <listitem>
     <para>
      Le nom de l'objet à commenter. Les noms des tables,
      agrégats, domaines, fonctions, index, opérateurs, séquences,
      types et vues pourraient être qualifiés du nom du schéma.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">texte</replaceable></term>
    <listitem>
     <para>
      Le nouveau commentaire.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   Il n'existe pas de mécanisme de sécurité pour les commentaires&nbsp;:
   tout utilisateur connecté à une base de données peut voir tous les
   commentaires des objets dans la base de données (bien que seuls les
   superutilisateurs peuvent modifier les commentaires sur des objets qu'ils
   ne possèdent pas). Du coup, ne placez pas d'informations critiques en terme
   de sécurité dans vos commentaires.
  </para>
 </refsect1>

 <refsect1>
  <title>Exemples</title>

  <para>
   Attacher un commentaire sur la table <literal>matable</literal>&nbsp;:

<programlisting>
COMMENT ON TABLE matable IS 'Ceci est ma table.';
</programlisting>

   Supprimez-le de nouveau&nbsp;:

<programlisting>
COMMENT ON TABLE matable IS NULL;
</programlisting>
  </para>

  <para>
   Quelques exemples supplémentaires&nbsp;:

<programlisting>
COMMENT ON AGGREGATE mon_agregat (double precision) IS 'Calcule une variance
type';
COMMENT ON COLUMN ma_table.ma_colonne IS 'Numéro employé';
COMMENT ON DATABASE ma_database IS 'Base de données de développement';
COMMENT ON DOMAIN mon_domaine IS 'Domaine des adresses email';
COMMENT ON FUNCTION ma_fonction (timestamp) IS 'Renvoie en chiffres romain';
COMMENT ON INDEX mon_index IS 'Renforce l'unicité de l'ID de l'employé';
COMMENT ON OPERATOR ^ (text, text) IS 'Traite l\'intersection de deux textes';
COMMENT ON OPERATOR ^ (NONE, text) IS 'Opérateur de préfix sur un texte';
COMMENT ON RULE ma_regle ON my_table IS 'Trace les mises à jour des
enregistrements d\'employé';
COMMENT ON SCHEMA mon_schema IS 'Données du département';
COMMENT ON SEQUENCE ma_sequence IS 'Utilisé pour générer des clés primaires';
COMMENT ON TABLE mon_schema.ma_table IS 'Informations sur les employés';
COMMENT ON TRIGGER mon_declencheur ON my_table IS 'Utilisé pour RI';
COMMENT ON TYPE complex IS 'Type de données pour les nombres complexes';
COMMENT ON VIEW ma_vue IS 'Vue des coûts départementaux';
</programlisting>
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibilité</title>

  <para>
   Il n'existe pas de commande <command>COMMENT</command> dans le standard SQL.
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->