search

mthom / scryer-prolog

A modern Prolog implementation written mostly in Rust.
BSD 3-Clause "New" or "Revised" License
1.93k stars 116 forks source link

Docs for library(reif) #2407

Closed razetime closed 1 week ago

razetime commented 1 month ago

WIP and some of the definitions are a bit wordy. Suggestions are very welcome.

triska commented 1 month ago

Thank you a lot for working on this! I have added a few comments and suggestions, and I hope others will also use this opportunity to discuss how to best document these important predicates.

UWN commented 1 month ago

There are many forms of reification. library(reif) chose one specific way.

mthom commented 3 weeks ago

I take it this is ready to be merged? Sorry for the delay

triska commented 3 weeks ago

Personally, I think this would still benefit from a few careful revisions. For instance, there is currently wording that is not applicable to logic programming, such as "returns true".

razetime commented 1 week ago

more changes. still not quite content but it resembles other documentation better. maybe the ones with shorter descriptions would be better off with an example.

razetime commented 1 week ago

if we are referencing call in the docs (which has too many overloads to list), how do we reference an arbitrary number of arguments?

UWN commented 1 week ago

Look, why don't you start by writing a separate tutorial with all kinds of uses first?

razetime commented 1 week ago

Look, why don't you start by writing a separate tutorial with all kinds of uses first?

maybe in general this work is better off left to someone who knows what they are doing.

triska commented 1 week ago

@razetime: Please don't let this particular outcome discourage you: These predicates are very hard to document in isolation, also because their definitions are so short that any documentation will likely far exceed the definitions themselves, likely rendering the documentation harder to understand than the actual definition. It is unlikely that anyone could have fared better at such an initial attempt of trying to squeeze the documentation into this format, thank you a lot for being the first to seriously try this!

A separate tutorial may indeed be a better and also more useful starting point, and I hope you continue to work on this!

razetime commented 1 week ago

yeah, i realized i was just adding redundant information, and i wasn't able to find the correct words for descriptions.. I will see if I can make a tutorial.