Suggestions for improving documentation

[igor84]

Suggestions for improving documentation

FAQ

• The question "Does Odin have any third-party library?" is not clear. Does it mean does Oding compiler depends on some third party libraries or are there third party libraries written in Odin? Maybe it could be worded better. I first got it wrong but now I think it means "Are there third party libraries written in Odin?".
• I understand all the reasons under "Why does Odin not have Uniform Function Call Syntax (UFCS)?" and they do make sense to me. But since the first mentioned goal of Odin is readability I would like to see examples that languages that do have it give as a readability advantage, somehow addressed here. Like:

	auto result = vector1.cross(vector2).transform(someMatrix).normalize().cross(vector3);
	auto totalFruitEURPrice = groceriesArray.filter(g => g.isFruit).map(g => g.usdPrice).map(convertUSDToEUR).sum();
	auto castingValuesAsSuffixExample = someFloat.to!int + someEnum.to!int ~ someIntArray.to!string; // last operator is string concatenation

Overview

• The term "Array programming" is confusing to me. I would preffer "Array operations".
• The sentence "We could write p^.x, however, it is to nice abstract the ability to not explicitly dereference the pointer." is not clear. Maybe "nice" should just be "nicely" or it needs to be worded differently.
• "Array of Structures of Arrays (AoSoA)" is mentioned but never explained or given examples for.
• Under "Implicit context system" example what is the point of c := context lines is not clear to me.
• How is separate context for each scope provided? Is new stack created on the stack it allocated on stack or heap with auto cleanup?
• The second sentence is not clear in: "new_clone - allocates a clone of the value passed to it. The resulting value of the type will be a pointer to the type of the value passed.". Maybe what was meant is: "The result is a pointer to a type of passed value that contains that passed value".
• Example under "Explicit context Definition" has a comment // Try commenting the following statement out below. I would prefer if instead it would say something like // If the following statement is commented out this and that would happen

[st142148]

FAQ

• There is not really any ambiguity, especially considering the one line answer literally points to a collection of libraries written in Odin. But you are right, your suggestion makes it extra clear.
• I mean... it is explained why Odin does not have UFCS. It is kind of pointless to then go on and explain why other languages do have it. For that you can look at their docs or the Wikipedia page. FAQ are supposed to be short and concise. Also the question "Why does Odin not have Uniform Function Call Syntax (UFCS)?" implies the reader knows what UFCS and its pros (and cons) are. (otherwise giyf)

Overview

• "Array programming" is an established term, and not just describing the feature. Also the first sentence links to the Wikipedia article and the example is as easy as it gets.
• That is actually just a typo and should probably read along the lines of: "We could write p^.x, however, it is nice to have the ability to not explicitly dereference the pointer."
• Well, kind of agree with this one. Mentioning AoSoA is not really adding anything, since it is not really its own thing, but just a combination of AoS and SoA. But then again, if you know those, you know AoSoA.
• This just shows that you have the ability to copy the context into your own variable, but is not used in the example otherwise. Maybe the comment could be clearer about that.
• You're right
• Agree. That comment makes it seem like a code-along tutorial like the rust book, not a general overview.

[igor84]

Regarding UFCS, I agree that the current text is sufficient so what I asked to be added is just a "nice to have". The text already covers one argument for UFCS: "dot-autocomplete" so I just felt that also covering the other argument which is readability in a similar manner would be "nice to have".

I missed that wiki link about Array Programming. Thanks for bringing it to my attention, I haven't seen it referred to like that before.

Anyway I think the documentation is great for a project at this stage and hope my read through with these tiny suggestions can make it even better. I learned a lot from it. Keep up the good work.

[st142148]

Regarding UFCS, I agree that the current text is sufficient so what I asked to be added is just a "nice to have". The text already covers one argument for UFCS: "dot-autocomplete" so I just felt that also covering the other argument which is readability in a similar manner would be "nice to have".

Of course I don't think more information would hurt. I guess it is more about personal preference about how extensive an FAQ should be.

Anyway I think the documentation is great for a project at this stage and hope my read through with these tiny suggestions can make it even better. I learned a lot from it. Keep up the good work.

Agree, although there is a long way to go. Like, I just noticed that technically the FAQ and overview are hosted on https://github.com/odin-lang/odin-lang.org . But much information is split off in this repo's wiki.

[gingerBill]

@igor84 Regarding your UFCS "readable" code, I am not even sure I understand what it does at a glance (without a deep reading of it).

auto result = vector1.cross(vector2).transform(someMatrix).normalize().cross(vector3);
auto totalFruitEURPrice = groceriesArray.filter(g => g.isFruit).map(g => g.usdPrice).map(convertUSDToEUR).sum();
auto castingValuesAsSuffixExample = someFloat.to!int + someEnum.to!int ~ someIntArray.to!string; // last operator is string concatenation

In Odin, that example would look something like this:

x := someMatrix * cross(vector1, vector2)
result := cross(normalize(x), vector3)

total_fruit_eur_price: Price
for g in groceries {
	if g.is_fruit {
		total_fruit_eur_price += convert_usd_to_eur(g.usd_price)
	}
}

cast_values_as_suffix_example := fmt.aprintf("%v%v", int(some_float) + int(some_enum), some_int_array)

Just making things inline does not make them any more readable, in fact it makes it more abstracted, and also subject to producing dreadful code generation too, especially in the filter/map case.

And in the casting and string concatenation case, the casting is a a little weird (but that is just syntax) and the string cast and the concatenation hides a memory allocation, which you don't want in Odin.

[igor84]

That is exactly what I was interested in: your view on those. Thank you for providing it.

Regarding casting syntax, that is something I recently realized is annoying to me in every language. My mind just never thinks in the order "and then I need to add, casted to int, this float variable", but always like this: "and then I need to add this variable and since it is float I need to cast it to int". This fact makes me always have to navigate back using arrow keys behind already typed variable in order to add the cast and then navigating back to the end :). And regarding readability of it, I find it equally readable as casting in front.

[gingerBill]

I experimented with x as T in the early days of Odin and it was not a pleasant experience since Odin is very C like. It may read fine if you view programming very in a more functional manner, but it does not work in a procedural mindframe.

I'm definitely not changing the syntax now, but I have found trying to make a language it is not is rarely a good idea.

[github-actions[bot]]

Hello!

I am marking this issue as stale as it has not received any engagement from the community or maintainers 120 days. That does not imply that the issue has no merit! If you feel strongly about this issue

• open a PR referencing and resolving the issue;
• leave a comment on it and discuss ideas how you could contribute towards resolving it;
• leave a comment and describe in detail why this issue is critical for your use case;
• open a new issue with updated details and a plan on resolving the issue.

The motivation for this automation is to help prioritize issues in the backlog and not ignore, reject, or belittle anyone..