Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

check that comments agree with hovers #72

Open
erniecohen opened this issue Jul 15, 2023 · 0 comments
Open

check that comments agree with hovers #72

erniecohen opened this issue Jul 15, 2023 · 0 comments

Comments

@erniecohen
Copy link

erniecohen commented Jul 15, 2023

Users who actually try the examples in VS Code will be confused when a comment disagrees with what they see when they hover. I think the first such example is

#check Nat.add -- Nat → Nat → Nat

A user reading the tutorial will be completely befuddled by the crosses and the superscript. The main problem is that this undermines reader trust, either in the tool or in the comments. (Note that this is different from leaving something unexplained; here you are saying that they will see one thing, and they actually see another.) You can avoid this by just having an explanation, a forward pointer, or some sort of warning in the comment, the hover, or in the text.

There are also examples where the comment should just be changed to match the hover, as in
#check ident -- ?m → ?m

@erniecohen erniecohen changed the title add note about inaccessible names check that comments agree with hovers Jul 15, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant