From f4135171afb43b420f582879ec22bbfed63700f8 Mon Sep 17 00:00:00 2001
From: Sven Verdoolaege <skimo@kotnet.org>
Date: Mon, 19 Apr 2010 11:18:42 +0200
Subject: [PATCH] doc: document *_get_dim functions

---
 doc/user.pod      | 16 ++++++++++++++++
 include/isl_map.h |  4 ++--
 include/isl_set.h |  4 ++--
 3 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/doc/user.pod b/doc/user.pod
index 426aa1d..f26a292 100644
--- a/doc/user.pod
+++ b/doc/user.pod
@@ -371,6 +371,22 @@ C<isl_dim_param>, C<isl_dim_in> (only for relations),
 C<isl_dim_out> (only for relations), C<isl_dim_set>
 (only for sets) or C<isl_dim_all>.
 
+It is often useful to create sets or maps that live in the
+same space as some other set or map.  This can be accomplished
+by creating the new sets or maps
+(see L<Creating New Sets and Relations>) based on the dimension
+specification of the original set or map.
+
+	#include <isl_set.h>
+	__isl_give isl_dim *isl_basic_set_get_dim(
+		__isl_keep isl_basic_set *bset);
+	__isl_give isl_dim *isl_set_get_dim(__isl_keep isl_set *set);
+
+	#include <isl_map.h>
+	__isl_give isl_dim *isl_basic_map_get_dim(
+		__isl_keep isl_basic_map *bmap);
+	__isl_give isl_dim *isl_map_get_dim(__isl_keep isl_map *map);
+
 =head2 Input and Output
 
 C<isl> supports its own input/output format, which is similar
diff --git a/include/isl_map.h b/include/isl_map.h
index a218fca..ac146ae 100644
--- a/include/isl_map.h
+++ b/include/isl_map.h
@@ -122,8 +122,8 @@ unsigned isl_map_n_out(const struct isl_map *map);
 unsigned isl_map_n_param(const struct isl_map *map);
 unsigned isl_map_dim(const struct isl_map *map, enum isl_dim_type type);
 
-struct isl_dim *isl_basic_map_get_dim(struct isl_basic_map *bmap);
-struct isl_dim *isl_map_get_dim(struct isl_map *map);
+__isl_give isl_dim *isl_basic_map_get_dim(__isl_keep isl_basic_map *bmap);
+__isl_give isl_dim *isl_map_get_dim(__isl_keep isl_map *map);
 
 struct isl_basic_map *isl_basic_map_alloc(struct isl_ctx *ctx,
 		unsigned nparam, unsigned in, unsigned out, unsigned extra,
diff --git a/include/isl_set.h b/include/isl_set.h
index c6e5237..f6ebe4b 100644
--- a/include/isl_set.h
+++ b/include/isl_set.h
@@ -85,8 +85,8 @@ unsigned isl_set_n_dim(const struct isl_set *set);
 unsigned isl_set_n_param(const struct isl_set *set);
 unsigned isl_set_dim(const struct isl_set *set, enum isl_dim_type type);
 
-struct isl_dim *isl_basic_set_get_dim(struct isl_basic_set *bset);
-struct isl_dim *isl_set_get_dim(struct isl_set *set);
+__isl_give isl_dim *isl_basic_set_get_dim(__isl_keep isl_basic_set *bset);
+__isl_give isl_dim *isl_set_get_dim(__isl_keep isl_set *set);
 
 struct isl_basic_set *isl_basic_set_alloc(struct isl_ctx *ctx,
 		unsigned nparam, unsigned dim, unsigned extra,
-- 
2.7.4