# Improvements to OCaml manual #1545

Merged
merged 4 commits into from Jan 25, 2018

## Conversation

Projects
None yet
7 participants
Contributor

### jfehrle commented Dec 24, 2017

 This will take some discussion, perhaps a lot.

### OvermindDL1 reviewed Dec 27, 2017

 They will be covered in more details later; for now, we concentrate on lists. Predefined data structures include tuples, arrays, and lists. There are also general mechanisms for defining your own data structures. These are records and classes, which will be covered in more detail later; for now, we concentrate on lists.

#### OvermindDL1 Dec 27, 2017

/me is not really a fan of even acknowledging classes exist this early...

#### Octachron Dec 27, 2017 • edited

Contributor

Introducing classes with the same level of importance as records and eclipsing variants is indeed a bad idea. People familiar with C++ or Java often misjudge the importance of classes in OCaml and this change may accentuate this problem. Contrarily echoing the title of the records and variants sections seems like a good idea. Mentioning that specialized data types like classes and polymorphic variants (and GADTs, extensible variants, and first-class modules) are also available might be a good compromise.

#### jfehrle Dec 28, 2017 • edited

Author Contributor

I'll take out the reference to classes and leave records as an example.

While I can frequently identify when something is confusing or missing, it's of course challenging for me as a novice to come up with specific changes to the wording and accurate details.

#### Octachron Dec 28, 2017

Contributor

I'll take out the reference to classes and leave records as an example.

I think citing variants at the same level of record would be nice, the two complements each other a lot and are fundamental parts of the type system.

While I can frequently identify when something is confusing or missing, it's of course challenging for me as a novice to come up with specific changes to the wording and accurate details.

Sorry if my tone was too dry, I really appreciate your contribution and it will make for a nice improvemen … after a bit of editing.

Contributor

### Octachron left a comment

 Thanks a lot for the contribution! I have however a lot of small comments and request for modifications.
 @@ -4,7 +4,7 @@ This part of the manual is a tutorial introduction to the OCaml language. A good familiarity with programming in a conventional languages (say, Pascal or C) is assumed, but no prior exposure to languages (say, C++ or Java) is assumed, but no prior exposure to

#### Octachron Dec 27, 2017

Contributor

I find this change detrimental: C++ or Java are too close from each other, readers might assume wrongly that a good familiarity with this family of language is required. If you are displeased with the relative obscurity of Pascal, one option might be to replace it with Javascript, Python, or any beginner language. Similarly, I see little point for replacing C with C++.

#### jfehrle Dec 28, 2017

Author Contributor

I'll go with "C or Javascript".

 They will be covered in more details later; for now, we concentrate on lists. Predefined data structures include tuples, arrays, and lists. There are also general mechanisms for defining your own data structures. These are records and classes, which will be covered in more detail later; for now, we concentrate on lists.

#### Octachron Dec 27, 2017 • edited

Contributor

Introducing classes with the same level of importance as records and eclipsing variants is indeed a bad idea. People familiar with C++ or Java often misjudge the importance of classes in OCaml and this change may accentuate this problem. Contrarily echoing the title of the records and variants sections seems like a good idea. Mentioning that specialized data types like classes and polymorphic variants (and GADTs, extensible variants, and first-class modules) are also available might be a good compromise.

 function defined above takes 2 arguments. Its type is therefore given as "'a -> 'a list -> 'a list". TODO: a sentence or two explaining why this notation was chosen and why it's preferred (eg to be more similar to mathematical logic)

#### Octachron Dec 27, 2017 • edited

Contributor

Explaining briefly the type of insert sounds like a good idea. However, this paragraph seems a bit clumsy and makes it sound like the notation used is totally arbitrary and have no link with currying. I would rather have a short explanation on the fact that insert takes two arguments here; and another paragraph in the "Function as values" section describing currying and why the notation 'a -> 'b -> 'c is natural.

#### jfehrle Dec 28, 2017

Author Contributor

The problem is that I don't know what should be said about the notation. I'm aware of currying but I couldn't explain why it is used and useful in OCaml. (Reading the wikipedia page on Currying doesn't cover that.)
I will drop the change unless one of you wants to suggest exact wording.

#### Octachron Dec 28, 2017

Contributor

A short description of the types may be enough here, more or less like the one used for sort may be enough here:

The type inferred for insert, 'a -> 'a list -> 'a list, means that insert takes two argument, an element of any type "'a" and a list of element of the same type "'a" and returns a list of the same type.

The explanation of partial application may be left to a later section and PR.

 @@ -373,8 +383,24 @@ g r;; \pdfsection{Exceptions} OCaml provides exceptions for signalling and handling exceptional conditions. Exceptions can also be used as a general-purpose non-local control structure. Exceptions are declared with the "exception" conditions.

#### Octachron Dec 27, 2017

Contributor

This change is far too opinionated, adding some words of caution might be fine, but not removing this sentence.

#### jfehrle Dec 28, 2017

Author Contributor

I believe the clear consensus among Java developers is that exceptions should be used for truly exceptional conditions and not as a non-local go to or an alternate way of returning a value. AFAIK this is not at all a controversial opinion. But perhaps this doesn't carry over to OCaml, or the consensus among OCaml developers is different.

I could say something like this (or just drop the change): "Exceptions can also be used as a general-purpose non-local control structure, although this should not be overused since it can make the code harder to understand."

#### Octachron Dec 28, 2017

Contributor

the consensus among OCaml developers is different.

I don't think that there is a clear consensus on this subject to be honest.

"Exceptions can also be used as a general-purpose non-local control structure, although this should not be overused since it can make the code harder to understand."

This sounds good.

 purpose control structure, which some would vigorously contest. My intention was to remove a controversial statement. But certainly this can be left unchanged. Can you explain how OCaml exceptions are more lightweight than in Java?

#### Octachron Dec 27, 2017

Contributor

May I suggest you to keep the discussion in the mantis ticket or in the github comments rather than in the source code itself?

#### jfehrle Dec 28, 2017

Author Contributor

Sure. It was expedient. Discussion in Mantis is more awkward than in github, and I made about 4 pages of comments there. @dra suggested "some of the smaller changes would be easier to discuss if you are able/willing to contribute a pull request"

#### Octachron Dec 28, 2017

Contributor

Sorry, I have not yet had the time to answer your question on the Mantis ticket. It is true that discussion on Mantis is a bit awkward on splintered discussion, but hiding questions in commits is a bit limited too.

 > the use of the word "messages" is largely accurate, I believe. I'm sure "sending messages" is the commonly used term by some. But I think it's not the term that would be used by Java/C++ developers. They would think of referencing

#### Octachron Dec 27, 2017

Contributor

Another point is that the manual is not aimed specifically to Java/C++ developper, it might be interesting to write an "OCaml for Java developpers" book but I do not think it is the primary objective of the manual. May I also repeat my statement that the manual source is not the place for a discussion?

#### jfehrle Dec 28, 2017

Author Contributor

I don't advocate turning this into an "OCaml for <language> developers". But the "sending messages" seems quite confusing for someone used to conventional languages. (To me it suggests creating a buffer, writing data into it, somehow "sending", ...)

I take the statement in the first paragraph of Chapter 1 as a metric for evaluating the contents of Part I of the manual ("This part of the language is a tutorial introduction to the OCaml language. A good familiarity with programming in a conventional language (say, Pascal or C) is assumed, but no prior exposure to functional languages is required.") This particular wording seems not to meet that standard--in my opinion.

Surely there is a clearer way to express this idea. If we can quickly agree on something better, let's go with it. If not, let's drop the suggestion and move on to things we can agree on.

#### Octachron Dec 28, 2017

Contributor

But the "sending messages" seems quite confusing for someone used to conventional languages

I think that the message metaphore was one of the original explanation for OO (it is used in smalltalk for instance). But since the word is used only once in chapter, you are probably right that it should be paraphrased.

#### xavierleroy Dec 29, 2017

Contributor

Yes, "sending messages" is Smalltalk terminology, but Smalltalk is the birthplace of OOP. Time for some Alan Kay quotes:

Actually I made up the term "object-oriented", and I can tell you I did not have C++ in mind.

I'm sorry that I long ago coined the term "objects" for this topic because it gets many people to focus on the lesser idea. The big idea is "messaging"

#### jfehrle Dec 29, 2017

Author Contributor

Yes, "sending messages" is Smalltalk terminology, but Smalltalk is the birthplace of OOP.
Time for some Alan Kay quotes:

Good quotes, but they recognize that common thinking/usage is not what Kay would prefer. Innovators put out their best ideas and the world may adapt them (or distort them or ignore them).

A method or an initializer can send messages to self (that is,
the current object).  (Or, in the terms used in mainstream
languages such as Java and C++, a method or an initializer can call
methods on the current object.)


#### Octachron Jan 2, 2018 • edited

Contributor

I fear that this sounds more like an armistice statement rather than a simple explanation.
I think going to the simpler version,

A method or an initializer can invoke methods on self (that is, the current object).

would be fine. There is definitively merit to try to spread potentially better terminology, but I think that the internal coherency of the chapter is more important here: methods are introduced in the first section with

We now invoke some methods to p:

Thus, reusing invoke may help readers.

 The "with" part is actually a regular pattern-matching on the exception value. Thus, several exceptions can be caught by one The "with" part does pattern matching on the exception value with the same syntax and behavior as "match". Thus, several exceptions can be caught by one

#### Octachron Dec 27, 2017

Contributor

The original sentence seems clearer to me, why did you think it was unclear?

#### jfehrle Dec 28, 2017

Author Contributor

My original comment in Mantis:

“The with part is actually a regular pattern-matching on the exception value.” “regular” makes me think of regular expressions. I think you mean it does the usual/normal pattern matching. Maybe
say “The with part does pattern matching on the exception value.”?

#### Octachron Dec 28, 2017

Contributor

or The "with" part is actually an usual pattern-matching on the exception value.
But your sentence seems fine too.

 introduced on a global level. However, you can give explicitly a data structure, keeping its polymorphism. Doing this requires user-provided type annotation, since polymorphism is only introduced automatically for global (top-level?) definitions.”

#### Octachron Dec 27, 2017

Contributor

global (top-level?) definitions."

First, there is a wandering " here. I would let global but the whole paragraph feels misplaced. I need to think about it.

#### jfehrle Dec 28, 2017

Author Contributor

let global

You mean keep "global" or remove "(top-level)"?

#### Octachron Dec 28, 2017

Contributor

I think leaving global is alright here.

 as arrays. Arrays are either given in extension between "[|" and "|]" brackets, or allocated and initialized with the "Array.make" as arrays. Arrays are either created by listing semicolon-separated element values between "[|" and "|]" brackets, or allocated and initialized with the "Array.make"

#### Octachron Dec 27, 2017

Contributor

This is nice!

 @@ -27,6 +27,8 @@ by ";;" in response to the "#" prompt, and the system compiles them on the fly, executes them, and prints the outcome of evaluation. Phrases are either simple expressions, or "let" definitions of identifiers (either values or functions). The ";;" is not necessary and generally not used in source files created for use with the OCaml compiler.

#### Octachron Dec 27, 2017

Contributor

I think this sentence would fit much better in the "Standalone Ocaml programs" section.

#### jfehrle Dec 28, 2017

Author Contributor

I'll move it. It seemed important to me to include so early because I've been looking at a lot of OCaml code in files. (Tangentially, many of the examples are far longer than you would ever type in to the top-level. In practice you would create files for them.)

The standalone OCaml program example at the end of page 24 uses ";;", which I think is not needed and so maybe should be removed.

#### Octachron Dec 28, 2017

Contributor

It seemed important to me to include so early because I've been looking at a lot of OCaml code in files

I agree that this an important point to keep in mind, at the same time this part of the manual is really focused on the interactive toplevel. Maybe a good option would be to add a forward reference or a footnote to the standalone program section for readers more interested in files.

The standalone OCaml program example at the end of page 24 uses ";;", which I think is not needed and so maybe should be removed.

This is an excellent idea!

#### jfehrle Dec 29, 2017

Author Contributor

I can remove two of the ";;". The one after "exit" is needed (gives a compile error without it). (Still figuring out OCaml syntax.)

let rec fib n =
if n < 2 then 1 else fib (n-1) + fib (n-2)
let main () =
let arg = int_of_string Sys.argv.(1) in
print_int (fib arg);
print_newline ();
exit 0;;
main ()


#### Octachron Dec 29, 2017

Contributor

A common OCaml idiom is to replace ;; main () with let () = main ().
An interpretation of the syntactical rule for ;; is that ;; is used to start (effectful) toplevel expressions.

### jfehrleforce-pushed the jfehrle:improve_doc branch 2 times, most recently from 9c90434 to 5d1e9fcJan 21, 2018

Contributor Author

### jfehrle commented Jan 21, 2018

 I updated 'Changes', which should make the required Travis job pass. @Octachron, any further review comments?

### Octachron reviewed Jan 21, 2018

 @@ -564,10 +564,6 @@ expr_n ')'@ evaluates to the n-ary variant value whose constructor is @constr@ and whose arguments are the values of @expr_1, \ldots, expr_n@. The expression @constr '('expr_1, \ldots, expr_n')'@ evaluates to the variant value whose constructor is @constr@, and whose arguments are the values of @expr_1 \ldots expr_n@.

#### Octachron Jan 21, 2018

Contributor

This change is an accident, isn'it?

#### jfehrle Jan 21, 2018

Author Contributor

My bad. Fixed. Thanks for reviewing.

Contributor

### Octachron commented Jan 21, 2018

 Overall, this looks fine; I will do a last review sometimes today.

Contributor

### Octachron left a comment

 I like the current changes, except for few minor nitpicking comments.
 mechanisms for defining your own data structures are also provided. They will be covered in more details later; for now, we concentrate on lists. Predefined data structures include tuples, arrays, and lists. There are also general mechanisms for defining your own data structures, such as records, which

#### Octachron Jan 21, 2018

Contributor

I would replace such as records by such as records and variants.

 Functors are functions'' from modules to modules. Functors let you create parameterized modules and then provide other modules as parameter(s) to get a specific implementation. For instance, a "Set" module implementing sets as sorted lists could be parameterized to work with any module that provides a type

#### Octachron Jan 21, 2018

Contributor

I would add a bit more context here: that provides a typethat provides a type of elements

#### jfehrle Jan 21, 2018

Author Contributor

Made this "that provides an element type", more idiomatic.

 let you create parameterized modules and then provide other modules as parameter(s) to get a specific implementation. For instance, a "Set" module implementing sets as sorted lists could be parameterized to work with any module that provides a type and a comparison method "compare" (such as "OrderedString"):

#### Octachron Jan 21, 2018

Contributor

I would use comparison function rather than method to avoid a potential confusion with object methods.

 @@ -2,15 +2,20 @@ \label{c:objectexamples} \pdfchapterfold{-15}{Tutorial: Objects in OCaml} %HEVEA\cutname{objectexamples.html} {\it (Chapter written by J�r�me Vouillon, Didier R�my and Jacques Garrigue)} {\it (Chapter written by J�r�me Vouillon, Didier R�my and Jacques Garrigue)}

#### Octachron Jan 21, 2018

Contributor

Am I a bit worried with this line, but this could be a problem with Github web interface. Could you check that this line does not exists in your local commit?

#### jfehrle Jan 21, 2018

Author Contributor

It doesn't appear as a change when I diff the commit. It may be that Github is expecting UTF-8 encoding for the accented characters (and would have multibyte representation) but that are probably in ISO 8851-1 (single byte).

Other changes applied as you suggested.

### xavierleroy reviewed Jan 22, 2018

 @@ -4,7 +4,7 @@ This part of the manual is a tutorial introduction to the OCaml language. A good familiarity with programming in a conventional languages (say, Pascal or C) is assumed, but no prior exposure to languages (say, C or Javascript) is assumed, but no prior exposure to functional languages is required. The present chapter introduces the

#### xavierleroy Jan 22, 2018

Contributor

It pains me to see Javascript mentioned. When we give examples of "conventional languages", can we choose some that don't completely suck? Java might do.

#### jfehrle Jan 22, 2018

Author Contributor

I originally mentioned Java, but the reviewer @Octachron thought that was too similar to C. I'll change it back to Java.

#### Octachron Jan 22, 2018

Contributor

I think I may have overeacted on your proposed couple (C++, Java), I am perfectly fine with (C, Java), even if the pair feels a bit close phylogenetically.

#### xavierleroy Jan 22, 2018

Contributor

Apologies for the back-and-forth. Java is a good middle ground here.

 exit 0;; main ();; exit 0 let () = main () \end{verbatim}

#### xavierleroy Jan 22, 2018

Contributor

The let () = ... trick is idiomatic but not intuitive at all. I see newcomers shaking their heads here.

#### jfehrle Jan 22, 2018

Author Contributor

Upon further reflection, I reverted the changes to the example and modified one sentence:

The ";;" used
in the interactive examples is not required in
source files created for use with the OCaml compiler, but can be helpful
to unambiguously mark the end of a top-level expression even when
there are syntax errors.


#### xavierleroy Jan 22, 2018

Contributor

That's reasonable. The alternative would be to explain the let () =  or let _ =  trick, but that can wait for another round of editing.

 @@ -219,7 +224,7 @@ in sections \ref{ss:reference-to-self} and \ref{ss:parameterized-classes}. \pdfsection{Reference to self} \label{ss:reference-to-self} A method or an initializer can send messages to self (that is, A method or an initializer can invoke methods on self (that is, the current object). For that, self must be explicitly bound, here to

Contributor

#### jfehrle Jan 22, 2018

Author Contributor

"methods on self" is commonly used, at least in the Java world.

#### xavierleroy Jan 22, 2018

Contributor

As you wish. I just wanted to make sure that "on" was not a typo for "of". But if "on" feels idiomatic to you, fine.

Contributor

### shindere commented Jan 22, 2018

 Xavier Leroy (2018/01/22 01:23 -0800): xavierleroy commented on this pull request. > @@ -4,7 +4,7 @@ This part of the manual is a tutorial introduction to the OCaml language. A good familiarity with programming in a conventional -languages (say, Pascal or C) is assumed, but no prior exposure to +languages (say, C or Javascript) is assumed, but no prior exposure to functional languages is required. The present chapter introduces the It pains me to see Javascript mentioned. When we give examples of "conventional languages", can we choose some that don't completely suck? Java might do. How about Python? Isn't it more widely taught and studied than Java, nowadays?
Contributor

### xavierleroy commented Jan 22, 2018

 Python is a lot more respectable than JavaScript, but to me it still hails from the "scripting languages" family more than from the "conventional languages" family. But, yes, it is the most "conventional" of the "scripting" languages, if this distinction makes any sense...

Contributor

### dra27 left a comment • edited

 I've only skimmed the technical discussions so far, so this is principally a review of the final language. It all looks like a nice improvement - main gripe for requesting changes is that there's still an editor encoding artefact present on some accented characters.
 They will be covered in more details later; for now, we concentrate on lists. Predefined data structures include tuples, arrays, and lists. There are also general mechanisms for defining your own data structures, such as records and variants, which

#### dra27 Jan 22, 2018

Contributor

Line-break shouldn't be here

#### jfehrle Jan 22, 2018

Author Contributor

Is it really necessary to fill and justify the rest of the paragraph (the next 5 lines) in the tex source when it has no effect on the appearance of the output? Seems to me it just makes more tedium for the editor and generates extraneous diffs in github. What is your thinking on this?

#### dra27 Jan 23, 2018 • edited

Contributor

I'm not sure what the standard for the manual is (@Octachron?), but this would certainly be yes for the main code base (e.g. for a re-worded documentation comment). While I completely agree that minimising diffs is important, so are coding standards and there are several places where I think the new lines also exceed the 80 char limit.

You're also assuming that the manual is only read after being TeX'd, but maybe I'm strange...

#### jfehrle Jan 23, 2018

Author Contributor

How about if we go for whatever @Octachron suggests?

(Adhering strictly to an 80 character limit is, BTW, an additional manual step for me--tedious to inspect and correct. There should be a tool to take care of this. But let's not dive into this debate.)

#### Octachron Jan 23, 2018 • edited

Contributor

For now, I don't think that there is a strongly enforced character-limit, even if the manual tend to follow a soft-limit of 70-72 characters.

However, I agree that this line-break disrupts the reading flow, and the changes required for respecting the character limit are very moderate:

variants, which will be covered in more detail later; for now, we concentrate
on lists. Lists are either given in extension as a bracketed list of

Note that for inspecting the 80 character limit, you can use the check-typo tools in the tools: ./tools/check-typo manual/manual/tutorials show that there is three new lines that goes beyond the character limit (the other lines were already here before), but this this can be fixed later.

#### jfehrle Jan 23, 2018

Author Contributor

I made all my changes less than 80 characters wide. Hope we're good now.

 @@ -110,11 +111,16 @@ sort [3.14; 2.718];; The "sort" function above does not modify its input list: it builds and returns a new list containing the same elements as the input list, in ascending order. There is actually no way in OCaml to modify in-place a list once it is built: we say that lists are {\em immutable} a list in place once it is built: we say that lists are {\em immutable}

#### dra27 Jan 22, 2018

Contributor

This should still be in-place with a hyphen, though the ordering is of course better.

#### jfehrle Jan 22, 2018

Author Contributor

"in place" is the common English usage, not "in-place", right? I moved the word and made this improvement.

#### dra27 Jan 23, 2018

Contributor

It's not common English, though - it's a technical term. cf. https://en.wikipedia.org/wiki/In-place_algorithm

#### jfehrle Jan 23, 2018

Author Contributor

OK

 "arg1_type -> arg2_type -> ... -> return_type". For example, the type inferred for insert, "'a -> 'a list -> 'a list", means that insert takes two arguments, an element of any type "'a" and a list of elements of the same type "'a" and returns a list of the same type.

#### dra27 Jan 22, 2018

Contributor

@Octachron - does the style of the manual does require some kind of formatting when referring to the insert function, too?

(text looks great, though!)

#### Octachron Jan 22, 2018

Contributor

I missed this point: Using "insert" when refering to the function named insert would be better (but not strictly required).

 type annotations, this is not allowed, as polymorphism is only introduced on a global level. However, you can give explicitly a data structure, keeping its polymorphism. Doing this requires user-provided type annotation, since polymorphism is only introduced

#### dra27 Jan 22, 2018

Contributor

Either "Doing this requires a user-provided type annotation" or "Doing this requires user-provided type annotations" (or the third possibility "Doing this requires user-providing type annotating", however I'm neutral on the first two options, but dislike this one!)

 @@ -409,11 +416,12 @@ name_of_binary_digit 0;; name_of_binary_digit (-1);; \end{caml_example} The "with" part is actually a regular pattern-matching on the exception value. Thus, several exceptions can be caught by one The "with" part does pattern matching on the

#### dra27 Jan 22, 2018

Contributor

I would personally say performs rather than does

 @@ -2,15 +2,20 @@ \label{c:objectexamples} \pdfchapterfold{-15}{Tutorial: Objects in OCaml} %HEVEA\cutname{objectexamples.html} {\it (Chapter written by J�r�me Vouillon, Didier R�my and Jacques Garrigue)} {\it (Chapter written by J�r�me Vouillon, Didier R�my and Jacques Garrigue)}

#### dra27 Jan 22, 2018

Contributor

Editor encoding artefact?

#### jfehrle Jan 22, 2018

Author Contributor

My local repository doesn't show any difference here, @Octachron thought it might be a github diff-code glitch because of the character encoding (ISO 8859-1 single byte vs UTF-8).

#### Octachron Jan 22, 2018

Contributor

A safer solution might be to use (Chapter written by J\'er\^ome Vouillon, Didier R\'emy and Jacques Garrigue) and then we could discuss later to change the encoding of the manual to utf-8.

#### jfehrle Jan 22, 2018

Author Contributor

I applied @Octachron 's suggestion.

#### dra27 Jan 23, 2018

Contributor

Note quite correctly, though - the letters themselves are missing after the accents. J\'er\^ome and R\'emy

#### jfehrle Jan 23, 2018

Author Contributor

Doh. Fixed.

 OCaml. Note that the relationship between object, class and type in OCaml is different than in Java and C++, so you shouldn't assume that similar keywords mean the same thing.

#### dra27 Jan 22, 2018

Contributor

"is different than differs from in Java and C++, so you one shouldn't assume that similar keywords mean the same thing have the same meaning."? (I realise the last part is not your text originally!)

#### jfehrle Jan 22, 2018

Author Contributor

These seem rather subjective--no single right/best way to word this.

As I see it: "... in OCaml is different than in Java and C++' has simple parallel construction with the 2 uses of "in <languages>". The bold part in your suggested "Note that the relationship between object, class and type in OCaml differs from in Java and C++" is itself awkward; "differs from that in" is more specific but feels pedantic.

"you" vs. "one": the document uses "you" and "your" in many places. Less formal and friendlier, seems OK to me.

"have the same meaning" vs "mean the same thing". The latter is a more active construction, the former is sort of a passive voice.

 Note that the relationship between object, class and type in OCaml is different than in Java and C++, so you shouldn't assume that similar keywords mean the same thing. Object-oriented features are used much less frequently in OCaml than in mainstream object-oriented languages such as Java and C++. OCaml has other

#### dra27 Jan 22, 2018

Contributor

The repetition of "such as Java and C++" is unnecessary here, IMO.

The word "other" is tautologous - "OCaml has alternatives"

#### jfehrle Jan 22, 2018

Author Contributor

Note that the relationship between object, class and type in OCaml is different than
in mainstream object-oriented languages such as Java and C++, so you shouldn't assume
that similar keywords mean the same thing.
Object-oriented features are used much less frequently in OCaml than
in those languages.  OCaml has other
alternatives that are often more appropriate, such as modules and functors.  Many
OCaml programs do not use objects at all.


From the dictionary: an alternative is "one of two or more available possibilities." Using obect-oriented features is an alternative in OCaml. "other alternatives" emphasizes excluding using object-oriented features. But if you feel strongly I will drop "other".

#### dra27 Jan 23, 2018

Contributor

Feel strongly is perhaps strong (!), but it mentions one thing (the object system) and then refers to the alternatives. To refer to the "other alternatives", there should be a reference to at least one alternative between the reference to the object system and the "other alternatives". 🙂

I like your point of wanting emphasis, though - perhaps it could be made by saying "several/many alternatives"?

#### jfehrle Jan 23, 2018

Author Contributor

Ah, I suspect we're not going to agree here so I will remove "other". In the bigger picture it doesn't matter.

To refer to the "other alternatives", there should be a reference to at least one alternative between the reference to the object system and the "other alternatives".

An alternative is "one of two or more available possibilities." Using object-oriented features is implicitly an alternative in OCaml since they they "are used much less frequently in OCaml".

#### Octachron Jan 23, 2018

Contributor

Stepping in as a non-native speaker, alternative has also a strong underlying connotation of another choice; and in other alternatives one may wonder if other is an emphatic redundancy or refers to yet another other possibility. I would prefer either several alternatives or other possibilities and avoid the potential ambiguity (and nuance) of the double negation in other alternatives.

 in Java and C++, so you shouldn't assume that similar keywords mean the same thing. Object-oriented features are used much less frequently in OCaml than in mainstream object-oriented languages such as Java and C++. OCaml has other alternatives that are often more appropriate, such as modules and functors. Many

#### dra27 Jan 22, 2018

Contributor

Nit: "which", rather than "that"

#### jfehrle Jan 22, 2018 • edited

Author Contributor

Though "which" may be more correct, I think "that" is the more common usage. I would have to look up the rule for when to use "which". The language evolves...

#### dra27 Jan 23, 2018

Contributor

Depends on your ivory tower (and definition of "evolution") 😉

 Object-oriented features are used much less frequently in OCaml than in mainstream object-oriented languages such as Java and C++. OCaml has other alternatives that are often more appropriate, such as modules and functors. Many OCaml programs do not use objects at all.

#### dra27 Jan 22, 2018

Contributor

Perhaps "Indeed, many OCaml programs do not use the object system at all."?

#### jfehrle Jan 22, 2018

Author Contributor

I added "indeed" but kept "objects".

Contributor

### dra27 commented Jan 24, 2018

 LGTM, thank you!
Contributor

### Octachron commented Jan 24, 2018

 @jfehrle , would you mind updating the list of reviewers? I will merge after this last details.
 Improve wording in several places in the OCaml manual, mostly in chapter 
1.
PR#7698
 a324021 

### jfehrleforce-pushed the jfehrle:improve_doc branch from 0ef05ad to a324021Jan 24, 2018

Contributor Author

### jfehrle commented Jan 24, 2018

 I added David to the list of reviewers. Thanks, guys.

### Octachron and others added some commits Jan 25, 2018

 manual: small fixes 
 ea7410e 
 Improve wording in several places in the OCaml manual, mostly in chapter 
1.
PR#7698
 52454d3 

### jfehrleforce-pushed the jfehrle:improve_doc branch from a324021 to 52454d3Jan 25, 2018

 Merge pull request #1 from Octachron/pr/1545 
manual: last minute  fixes
 2bd9949 

### Octachron merged commit 261c714 into ocaml:trunk Jan 25, 2018 2 checks passed

#### 2 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
Contributor

### Octachron commented Jan 25, 2018

 Merged. Thank you for you contribution, and your patience during the review process!