Documentation needs more explanation for in-memory url in tutorial/toh-pt6
MickeySegal opened this issue · 2 comments
The section about the in-memory URL in the HTTP chapter of the Angular tutorial needs more detail to be clear.
The material at https://angular.io/tutorial/toh-pt6 introduces the 'api/heroes' syntax with no explanation other than the inline comment:
private heroesUrl = 'api/heroes'; // URL to web api
However, it is confusing to what api refers, and using app or apd instead works just as well. More importantly, it is unclear to what heroes refers. For example, the demo does have a heroes path in Routes and a heroes component, but heroesUrl actually refers to the heroes object used in in-memory-data-service.ts
A blog post by Brian Swartzfager's at http://www.thoughtdelimited.org/thoughts/post.cfm/learning-angular-2-tour-of-heroes-tutorial-lesson-7 makes the same point.
A StackOverflow question at https://stackoverflow.com/questions/40841523/understanding-http-in-angular-2-tutorial asks the same question and got a correct but unhelpful answer.
After locating the documentation at https://www.npmjs.com/package/angular-in-memory-web-api the syntax and its meaning became less opaque, but the Angular tutorial does not mention this. Fiddling with the live example at https://angular.io/generated/live-examples/toh-pt6/eplnkr.html was helpful, but the documentation should explain what this "URL to web api" is doing and to what heroes points.
Suggestions for improving the documentation:
- Explain the meaning of the api/heroes syntax in the documentation. The explanation of "URL to web api" is too terse to mean anything to someone who hasn't used the in-memory-web-api package. Also include a link to documentation at https://www.npmjs.com/package/angular-in-memory-web-api or some better URL.
- When constructing demos, try to avoid using the same word such as heroes for multiple different items, such as paths, files and data objects. In cases such as here where a data object is referred to with the same name as a path, it muddies the water to give 3 different things the same name, particularly when the tutorial refers to the data object with a URL that looks like a path.
Open it again in the right repo (angular/angular) please.
Done at angular/angular#18869 but there are no signs of activity. Is there a better place than angular/angular?