potassco / potassco/constraint-handler

Vague naming of execution tag/group identifier in the documentation

Open
#186 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
3
Forks
0
Avg merge
1d 19h
Merged PRs (30d)
20

Description

I was just wandering if you'd consider changing some descriptions in the documentation...

In the core syntax reference, https://github.com/potassco/constraint-handler/blob/master/docs/reference/core_syntax.md, I find the name used for the execution group/tag identifier to be too vague to be useful.

For example for variable_define/3 it is simply says Identifier with the description being "A unique identifier for this specific Declaration".

While I think I understand how to use it now, someone new coming to the constraint handler would be no better informed by reading such a description, and could in fact be left even more confused.

So I was wondering if it is consider some alternatives:

To me it seems to be linked directly to the requestEngine/2 facts so I would think some variant of "Execution/Engine Group/Tag" seems reasonable. But maybe there are other ways to use this tag so maybe there is something more general that can be used. Or maybe it is just the description that needs to be expanded to make it more understandable?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with docs/reference/core_syntax.md and inspect the descriptions for variable_define/3 and related execution group or tag identifiers. Trace the requestEngine/2 facts and surrounding syntax to determine the identifier’s role and supported uses. Done means the documentation uses a precise, consistent name and explains the identifier clearly enough for a newcomer.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.