apple / apple/pkl

Language tutorial "Writing a Template" is confusing sometimes

Open
#744 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
11.5k
Forks
402
Avg merge
1d 15h
Merged PRs (30d)
20

Description

[This](https://github.com/apple/pkl/blob/release/0.26/docs/modules/language-tutorial/pages/03_writing_a_template.adoc?plain=1#L170-L247) whole section talks about `pklTutorialPart3.pkl` which had not been defined up to that point. Additionally, it's talking about types and classes and then shows an example of amending that has no classes (`TutorialPart.pkl` and `pklTutorialPart3.pkl`).

It goes on to [say](https://github.com/apple/pkl/blob/release/0.26/docs/modules/language-tutorial/pages/03_writing_a_template.adoc?plain=1#L246-L247):

```
This now behaves exactly like our pklTutorialPart3: TutorialPart = (pklTutorialPart1) {…​ before. pklTutorialPart3 is now defined as the value we get by amending tutorialPart and giving it a name and a part
```

Ok, it behaves exactly like that so then what's the point of using a class (I know the point, I don't understand why the tutorial is going down this path).

Contributor guide

Open the contributing guide

Research direction

Read docs/modules/language-tutorial/pages/03_writing_a_template.adoc, especially lines 170-247. Trace where pklTutorialPart3.pkl is first introduced and compare the discussion of types and classes with the TutorialPart.pkl and pklTutorialPart3.pkl examples. Done means the section defines its examples in order and explains why the class-based path is useful.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.