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

docs: Clarify important points about parametric types #43891

Open
wants to merge 9 commits into
base: master
Choose a base branch
from

Conversation

adigitoleo
Copy link
Contributor

Closes #43811.

  • The intro section felt a bit long-winded, I've made some changes there first.
  • Clarify that typeof returns the concrete type
  • Rename Type Declarations section to Type Annotations,
    avoid confusion with Declaring Types section and distinguish use of "type declaration"
    to mean "declaring new types"
  • Removed some of the jargon and wikipedia links to make room for
    a brief alternative Point{T1,T2} demonstration.
  • Shifted some paragraphs around to reflect their importance,
    and changed the wording in some places.
  • Rename type declaration -> annotation in other places (docstrings/comments)

@adigitoleo
Copy link
Contributor Author

adigitoleo commented Jan 22, 2022

Couldn't find a good place to add a complete custom type family example, and the section is already quite long. Maybe that can go somewhere else eventually.

@adigitoleo
Copy link
Contributor Author

One other thing I left out compared to the linked issue was talking about DataType, because that has it's own section in Declaring Types.

I do think that Declaring Types needs a bit of work as well, but I'll leave it for another PR.

@vtjnash vtjnash added the docs This change adds or pertains to documentation label Jan 24, 2022
@StefanKarpinski
Copy link
Member

This seems fairly good, but https://github.com/JuliaLang/julia/pull/43891/files#diff-ff6fac0d94f573935b4028dee9bd538f1e1527fde287a3e247394dc16a7fc701 is quite hard to review because of the formatting changes. I guess I'll have to read the whole thing to make sure it makes sense and also check that it doesn't delete anything important from the original.

@adigitoleo
Copy link
Contributor Author

Happy to revert the formatting if it helps. I automatically adopted my markdown habits of breaking at sentence clauses, which I find to produce comfy diffs (except for the first time it's done, like here).

Here's the built html of that page, if it helps: https://x0.at/Bw6y.txt

@StefanKarpinski
Copy link
Member

StefanKarpinski commented Mar 24, 2022

That would be great if you could. I also prefer that style, but it makes the diff here too big and hard to read. You could separate the change into purely formatting and actual content changes as well and then I can just review the content change.

@adigitoleo

This comment was marked as resolved.

@fingolfin
Copy link
Contributor

Overall this looks quite good to me! It is a pity that it sat around here for almost 2 years :-(. @adigitoleo sorry for that, if you are still willing to work on it, perhaps you can resolve the conflict?

@StefanKarpinski I think this is relatively nice to review now, perhaps you'd be willing to have another look at it?

doc/src/manual/types.md Outdated Show resolved Hide resolved
doc/src/manual/types.md Outdated Show resolved Hide resolved
doc/src/manual/types.md Outdated Show resolved Hide resolved
doc/src/manual/types.md Outdated Show resolved Hide resolved
@adigitoleo
Copy link
Contributor Author

Thanks for the review. Conflicts should be resolved now. I've addressed the comments, but I'm not sure of the etiquette: should I mark conversations as resolved or leave that to maintainers?

adigitoleo and others added 3 commits June 3, 2024 23:39
Closes JuliaLang#43811.

- The intro section felt a bit long-winded, I've made some changes there first.
- Clarify that `typeof` returns the concrete type
- Rename Type Declarations section to Type Annotations,
  avoid confusion with Declaring Types section and distinguish use of "type declaration"
  to mean "declaring new types"
- Removed some of the jargon and wikipedia links to make room for
  a brief alternative `Point{T1,T2}` demonstration.
- Shifted some paragraphs around to reflect their importance,
  and changed the wording in some places.
- Rename type declaration -> annotation in other places (docstrings/comments)
@oscardssmith
Copy link
Member

I think this is ready to merge, right?

@adigitoleo
Copy link
Contributor Author

Just rebased on lates master, haven't looked at the bulk of the changes in a while but it has been reviewed before. Should be good to go from my side.

and dynamic type systems, where types are only computed at run time,
when the actual values manipulated by the program are available.
Statically typed languages typically offer faster execution,
at the cost of type annotations which must be explicitly added by the programmer.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Explicit annotations are not required in many statically typed languages, e.g. with Hindley–Milner type systems, which (like Julia) use type inference.

The difference, as @StefanKarpinski has often put it, is that in a static language it is an error if type inference fails, whereas in a dynamic language like Julia the inference is just an optimization.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good points, thanks. How about this for the first paragraph:

Types in Julia establish distinctions between different kinds of data, and are used by the compiler to infer the intended use of those data. Programming languages have traditionally employed one of two quite different type systems: static type systems, where expressions must have a computable type before the execution of the program, and dynamic type systems, where types are only computed at run time, when the actual values manipulated by the program are available. Statically typed languages typically offer faster execution of programs, while treating any data of unknown or invalid type as an error. In these languages, the programmer is responsible for ensuring the validity of all types of data that the program may encounter. Dynamically typed languages, on the other hand, do not explicitly check types, and types of data only become invalid when they fail to support run-time operations.

Copy link
Member

@stevengj stevengj Aug 2, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Statically typed languages typically offer faster execution of programs

The whole point of Julia is that this is not true — they are not any faster than type-stable code in Julia. The main argument for static typing, IMO, is safety — by being stricter about types, the compiler can catch more bugs. (And, of course, there are tradeoffs, e.g. in making interactive exploration more difficult.)

But the pros and cons of static vs. dynamic languages is a longstanding debate and a bit of a can of worms here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess by "typically" I probably meant "usually", but I can understand if this unintentionally suggests that Julia is not performant. I'll think about a better wording here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think "usually" is any better

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Statically typed languages offer stricter guidance for avoiding unsafe code, such as treating any data of unknown or invalid type as an error. In these languages, the programmer is responsible for ensuring the validity of all types of data that the program may encounter. Writing programs in statically typed languages is, therefore, more laborious, and interactive exploration of data at run-time becomes more difficult. Dynamically typed languages, on the other hand, do not explicitly check types, and types of data only become invalid when they fail to support run-time operations. This provides a more flexible and productive programming experience, at the cost of a greater potential for programmer errors to cause bugs during execution.

?

doc/src/manual/types.md Outdated Show resolved Hide resolved
doc/src/manual/types.md Outdated Show resolved Hide resolved
@adigitoleo

This comment was marked as outdated.

doc/src/manual/types.md Outdated Show resolved Hide resolved
doc/src/manual/types.md Outdated Show resolved Hide resolved

!!! warning
Type parameters are invariant: even though `Float64 <: Real`,
the relation `Foo{Float64} <: Foo{Real}` does NOT hold for any parametric type `Foo`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
the relation `Foo{Float64} <: Foo{Real}` does NOT hold for any parametric type `Foo`.
the relation `Foo{Float64} <: Foo{Real}` does NOT hold for any parametric type `Foo`.

of course except for Tuple

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't know about that, thanks. Is there a reason why that is the case that we can/should highlight here?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not familiar with all the details but my understanding is that the reason for covariance is largely vestigial; it made dispatch easier in the early days of Julia or something

Tuple type covariance is described here in the docs https://docs.julialang.org/en/v1/manual/types/#Tuple-Types-1

and there is an open issue discussing the potential to switch to invariance in a hypothetical breaking release of Julia (although as a gambling man, I wouldn't put my money on that change ever happening) #24614

I would think a quick link to the docs is probably sufficient

doc/src/manual/functions.md Outdated Show resolved Hide resolved
doc/src/manual/types.md Outdated Show resolved Hide resolved
doc/src/manual/types.md Outdated Show resolved Hide resolved
doc/src/manual/types.md Outdated Show resolved Hide resolved
doc/src/manual/types.md Outdated Show resolved Hide resolved
adigitoleo and others added 2 commits August 5, 2024 23:48
Co-authored-by: adienes <51664769+adienes@users.noreply.github.com>
Co-authored-by: adienes <51664769+adienes@users.noreply.github.com>
@adigitoleo
Copy link
Contributor Author

Thanks again everyone, a few minor points to clarify from the review by @adienes and about the first paragraph (@stevengj, see #43891 (comment)).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs This change adds or pertains to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Better introduction to parametric types in the manual
7 participants