From 2ac7d06a503b256b290678f5bba158bf7d219bdd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Thu, 4 Aug 2022 16:26:27 +0200
Subject: Add comments.

---
 c/pl.h | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

(limited to 'c/pl.h')

diff --git a/c/pl.h b/c/pl.h
index 5720eda..b0cdbbd 100644
--- a/c/pl.h
+++ b/c/pl.h
@@ -7,19 +7,23 @@
 
 #include "wcharptr.h"
 
+/* Convert Prolog term to wide characters. */
 WcharPtr PlString(const term_t t, const int flags = CVT_WRITE);
 
+/* Wrapper for opening and closing Prolog foreign frames. */
 struct Frame
 {
 	Frame();
 	~Frame();
 	void Close();
+	/* Close foreign frame AND invalidate associated data. */
 	void Discard();
 	void Rewind();
 private:
 	fid_t m_f;
 };
 
+/* Wrapper for marking and releasing strings on the Prolog stack. */
 struct Mark
 {
 	Mark();
@@ -28,12 +32,14 @@ private:
 	buf_mark_t m_m;
 };
 
+/* Wrapper for opening, solving and cutting Prolog query. */
 struct Query
 {
 	Query(module_t ctx, predicate_t p, term_t t0);
 	~Query();
 	int Cut();
 	int Cut(std::nothrow_t);
+	/* Cut query AND invalidate associated data. */
 	int Close();
 	int Close(std::nothrow_t);
 	int NextSolution();
@@ -67,12 +73,13 @@ inline int PlGet(term_t t, long* x) { return PL_get_long(t, x); }
 inline int PlGet(term_t t, long long* x) { return PL_get_int64(t, x); }
 inline int PlGet(term_t t, atom_t* x) { return PL_get_atom(t, x); }
 inline int PlGet(term_t t, char** x) { return PL_get_atom_chars(t, x); }
-inline int PlGet(term_t t, WcharPtr* x) {
+inline int PlGet(term_t t, WcharPtr* x)
+{
 	Mark m;
 	char* s;
 	if (!PlGet(t, &s)) return 0;
 	*x = WcharPtr::FromNarrow(s);
-	return 1; /* or catch potential exception from BstrFromSz? */
+	return 1;
 }
 
 /* Put in or get from a term reference an arbitrary number of values,
-- 
cgit v1.2.3