potassco / potassco/constraint-handler
Vague naming of execution tag/group identifier in the documentation
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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