# Is the documentation of library(heaps) confusing?

**URL:** <https://swi-prolog.discourse.group/t/is-the-documentation-of-library-heaps-confusing/9259>\
**Category:** PlDoc\
**Tags:** discussion\
**Created:** [September 9, 2025, 10:31am UTC](https://swi-prolog.discourse.group/t/is-the-documentation-of-library-heaps-confusing/9259 "2025-09-09T10:31:30Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![Boris](https://yyz2.discourse-cdn.com/free1/user_avatar/swi-prolog.discourse.group/boris/32/7486_2.png) [@Boris](https://swi-prolog.discourse.group/u/Boris)\
**Post date:** [September 9, 2025, 10:31am UTC](https://swi-prolog.discourse.group/t/is-the-documentation-of-library-heaps-confusing/9259/1 "2025-09-09T10:31:31Z")

</div>

Maybe it is just me. I _think_ the underlying reason is the generous use of the forward slash [in the text](https://www.swi-prolog.org/pldoc/man?section=heaps). For example, we find the following pairs (with a bit of context, because I am not even sure how should this parse, if we would strictly follow the author’s intention)

> library(heaps): heaps/priority queues

> a central element of algorithms such as best-first/A\* search and Kruskal’s minimum-spanning-tree algorithm

> meaning that items are retrieved in ascending order of key/priority

> Although the data items can be arbitrary Prolog data, keys/priorities must be ordered by [@=\</2](https://www.swi-prolog.org/pldoc/man?predicate=@%3D%3C/2)

This all sounds _okey_ until the predicate definitions, which look like this:

> **add\_to\_heap** (_+Heap0, +Priority, ?Key, -Heap_)
> 
> Adds _Key_ with priority _Priority_ to _Heap0_, constructing a new heap in _Heap_.

Here is an attempt to demonstrate that the _Priority_ from the definition above is used; but the _Key_ is not. I used _X_ and _Y_ in the queries so that I don’t have to name it something confusing. The docs claim:

> **min\_of\_heap** (_+Heap, ?Priority, ?Key_)
> 
> Unifies _Key_ with the minimum-priority element of _Heap_ and _Priority_ with its priority value. Complexity: constant.

```prolog
?- empty_heap(_H0),
   add_to_heap(_H0, 1, foo, _H1),
   add_to_heap(_H1, 1, bar, _H2),
   min_of_heap(_H2, X, Y).
X = 1,
Y = bar.

?- empty_heap(_H0),
   add_to_heap(_H0, 1, bar, _H1), % same elements
   add_to_heap(_H1, 1, foo, _H2), % but inserted in different order
   min_of_heap(_H2, X, Y).
X = 1,
Y = foo.

```

This is also easily seen [in the source code](https://www.swi-prolog.org/pldoc/doc/_SWI_/library/heaps.pl?format_comments=false&show=src).

The use of “key/priority” in the docs, together with the naming of the arguments, is in my opinion inconsistent. I suspect the original author meant to use “key/priority” when documenting the second argument from the definition of add\_to\_heap/4 above, and use “data item” for the third argument.

Am I tripping? Is this a bit confused or is it me? I can make a PR if it turns out that other are also confused.

PS: the docs are confusing at first but the library itself is quite useful!

---

<div class="post-metadata">

**Author:** ![jan](https://yyz2.discourse-cdn.com/free1/user_avatar/swi-prolog.discourse.group/jan/32/4_2.png) [@jan](https://swi-prolog.discourse.group/u/jan)\
**Post date:** [September 9, 2025, 11:04am UTC](https://swi-prolog.discourse.group/t/is-the-documentation-of-library-heaps-confusing/9259/2 "2025-09-09T11:04:53Z")

</div>

> [@Boris](#):
>
> Am I tripping? Is this a bit confused or is it me? I can make a PR if it turns out that other are also confused.

It seems there are some opportunities for improvement 🙂 Just file a PR.

---

<div class="post-metadata">

**Author:** ![Boris](https://yyz2.discourse-cdn.com/free1/user_avatar/swi-prolog.discourse.group/boris/32/7486_2.png) [@Boris](https://swi-prolog.discourse.group/u/Boris)\
**Post date:** [September 9, 2025, 12:31pm UTC](https://swi-prolog.discourse.group/t/is-the-documentation-of-library-heaps-confusing/9259/3 "2025-09-09T12:31:23Z")

</div>

> [@jan](#):
>
> It seems there are some opportunities for improvement 🙂 Just file a PR.

Great, will do.

This is my general proposal:

- Explain that the Key is the Priority and the Priority is the Key
- consistently use “Priority” in the predicate documentation and get rid of “Key”
- Call the other thing “Data item” or just “Value”.

Open to other suggestions.

---

<div class="post-metadata">

**Author:** ![Boris](https://yyz2.discourse-cdn.com/free1/user_avatar/swi-prolog.discourse.group/boris/32/7486_2.png) [@Boris](https://swi-prolog.discourse.group/u/Boris)\
**Post date:** [September 9, 2025, 3:29pm UTC](https://swi-prolog.discourse.group/t/is-the-documentation-of-library-heaps-confusing/9259/5 "2025-09-09T15:29:25Z")

</div>

> [@jp-diegidio](#):
>
> In fact, there is not even prescription that the key/priority (in the sense I have now fixed, so distinct from the item/data), has to be ground.

At the moment the documentation already says:

> Although the data items can be arbitrary Prolog data, keys/priorities must be ordered by [@=\</2](https://www.swi-prolog.org/pldoc/man?predicate=@%3D%3C/2). Be careful when using variables as keys, since binding them in between heap operations may change the ordering.

This is strong enough. You can use variables (there might be valid use cases) but you must remember that binding them will change their ordering in respect to other priorities/keys.

> [@jp-diegidio](#):
>
> That said, I’d propose that what is now called Key should rather be called Item (in fact I’d propose to also change “entry”/“entries” to “item”/“items” in all places – anyway, this is the “data”): then it is also easier to explain that the “priority” is equivalently a key into the data.

Yes, this is roughly my plan, as described in my previous post. It is just not clear which Key mentions you mean. I am aiming to remove completely the **use of the argument name _Key_ in predicate declarations** and most probably rename it to _Value_. So, it will be _Priority_ - _Value_ but maybe _Priority_ - _Item_ also works. It might in fact make the re-write smaller.

---

<div class="post-metadata">

**Author:** ![jan](https://yyz2.discourse-cdn.com/free1/user_avatar/swi-prolog.discourse.group/jan/32/4_2.png) [@jan](https://swi-prolog.discourse.group/u/jan)\
**Post date:** [September 9, 2025, 3:47pm UTC](https://swi-prolog.discourse.group/t/is-the-documentation-of-library-heaps-confusing/9259/6 "2025-09-09T15:47:20Z")

</div>

> [@Boris](#):
>
> So, it will be _Priority_ - _Value_ but maybe _Priority_ - _Item_ also works. It might in fact make the re-write smaller.

Do not forget that Priority does not need to be a number, but the total ordering implied by the Prolog standard order of terms (don’t mention cyclic terms 🙂 ) In that sense `Key-Value` could do fine as well?

---

<div class="post-metadata">

**Author:** ![Boris](https://yyz2.discourse-cdn.com/free1/user_avatar/swi-prolog.discourse.group/boris/32/7486_2.png) [@Boris](https://swi-prolog.discourse.group/u/Boris)\
**Post date:** [September 9, 2025, 3:55pm UTC](https://swi-prolog.discourse.group/t/is-the-documentation-of-library-heaps-confusing/9259/7 "2025-09-09T15:55:08Z")

</div>

Yes, of course. In this case the intro will have to explain that the key is the priority (and the priority the key…). I will go with this then.