WIP: Document noteworthy unusual Julia features. #11998
Conversation
Ref: #11966 Document unicode identifiers. [av skip]
| ret | ||
| end | ||
|
|
||
| But be wary... |
There was a problem hiding this comment.
Maybe add something about the two example cases that you need to be wary about (referencing a global variable thinking it was an operator applied to a local variable), and updating a variable without remembering to update the cached value.
The other example, of / returning a different type than it's arguments, and needing to use div
for integer division, along with the possibility of losing digits, should also be added.
Good that you are doing this! I wish I'd had this a couple of months ago!
[ci skip] Check whitespace latter when squashing commits.
[ci skip]
[ci skip]
[ci skip]
[ci skip]
[ci skip]
|
|
||
| .. note:: | ||
|
|
||
| Be wary about referencing a global variable while thinking it was an operator applied to a local variable and updating a |
There was a problem hiding this comment.
I have no idea what this sentence is trying to say. Could you word it differently? Is this related to unicode?
There was a problem hiding this comment.
@ScottPJones would you mind showing a short example of this pitfall?
There was a problem hiding this comment.
This "pitfall" is a contrived strawman crafted to make a specific point.
|
I find it really problematic to have a section like this in the manual. What counts as "unusual" is highly subjective. Specific items like how |
|
@JeffBezanson what I would really want, is more people describing more differences with short examples, so that they can be documented in whatever section they end up being needed. Also I know it's subjective but Julia is indeed unusual in many ways, I don't care about the title, it could be whatever we see fit. All I want is better documentation. |
|
What I mean is that some features are not only noteworthy different to just one specific language, but instead are different to many languages at once, which is why some comparisons don't belong into just one particular language section (and redundancy is ugly), another purpose of this document is to concentrate this kind of stuff, instead of having it spread all over the manual. |
|
If you know language X, then documenting differences with language X is useful. I don't understand the utility of documenting things that are considered different from nothing in particular. Who is the intended audience? |
|
You are assuming that there must be only a one to one relationship between each Julia feature with each other language. All I want is to avoid redundancy (if a feature is related to more than one language) and centralize this kind of information (ie. the style advices are scattered) , but if you guys think it's useless feel free to close this. |
|
The example could probably go in http://docs.julialang.org/en/latest/manual/interacting-with-julia/ if you want to split out to a new PR. Thanks! |
Ref: #11966
Document unicode identifiers.
[av skip]