Add type annotations to code examples in "Getting Started"

purescript / documentation

Documentation for the PureScript language, compiler, and tools.

Other

1.02k stars 301 forks source link

Add type annotations to code examples in "Getting Started" #318

Open hdgarrood opened 4 years ago

hdgarrood commented 4 years ago

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 commented 4 years ago

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

milesfrain commented 4 years ago

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.

hdgarrood commented 4 years ago

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

oldfartdeveloper commented 1 year ago

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.