documentation icon indicating copy to clipboard operation
documentation copied to clipboard

Add type annotations to code examples in "Getting Started"

Open hdgarrood opened this issue 4 years ago • 4 comments

People will probably not expect the code examples they encounter in the Getting Started guide to emit warnings, but right now, they do, because they do not include type annotations. It may be worth changing the guide to include type annotations, because beginners might think that warnings indicate a problem. See also the discussion in #305.

hdgarrood avatar May 20 '20 22:05 hdgarrood

I'm leaning towards doing this but I'm not completely certain.

hdgarrood avatar May 20 '20 22:05 hdgarrood

Leaning against this because:

  • The guide notes that warnings will appear. Maybe this point in the text just needs some emphasis.
  • These compiler warnings are fairly human-friendly.
  • The type annotations introduce more unknown and potentially confusing content.

milesfrain avatar May 21 '20 22:05 milesfrain

The types will be encountered anyway - if they're not present in the examples, then the warning suggests adding them and writes them out for you:

    No type declaration was provided for the top-level declaration of main.
    It is good practice to provide type declarations as a form of documentation.
    The inferred type of main was:
                 
      Effect Unit

hdgarrood avatar May 25 '20 18:05 hdgarrood

I agree with @hdgarrood on this. But I also agree w/ @milesfrain. There are good arguments on both sides. For that reason, I don't feel it's worthwhile pursuing this any longer; it has lingered long enough. Hence agree with the earlier closing.

oldfartdeveloper avatar Dec 29 '22 21:12 oldfartdeveloper