warnings on code snippets are distracting attention from purpose
Nobody has claimed this yet.
- Dominant language
- Ada
- Stars
- 117
- Forks
- 49
- Avg merge
- 44m
- Merged PRs (30d)
- 8
Description
Looking at the messages from running builds on code snippets in the course "Introduction to Ada", it seems to me that code snippets should be reworked to avoid distracting warnings that do not correspond to the issue being illustrated by the code snippet.
As an example, take the chapter on Arrays. In the section on "Predefined array type: String", hitting Run on the first "greet" code snippet issues this warning:
greet.adb:4:04: warning: "Message" is not modified, could be declared constant [-gnatwk]
This is highlighted in red, pointing to something the user might consider important here. It is not. The constant should in fact be declared with "constant" keyword to avoid that warning.
Take the "main" example that follows. Hitting Run generates three warnings, again highlighted in red:
main.adb:1:09: warning: no entities of "Ada.Text_IO" are referenced [-gnatwu]
main.adb:1:19: warning: use clause for package "Text_IO" has no effect [-gnatwu]
main.adb:7:04: warning: constant "My_Array" is not referenced [-gnatwu]
This could be avoided for the first two lines by removing the useless reference to Ada.Text_IO (which looks like a good idea anyway as this is not used for the explanation of this code snippet), but that would not work for the last line. Here, given the incomplete nature of code snippets, where you may end up declaring entities that are not used (code ellipsis), I recommend to compile the code of this snippet and all others with the switch -gnatwU.
This is a general comment that applies to all the content on learn, but in particular to the content of the course "Introduction to Ada", since newcomers are more likely to get confused by such messages.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the “Introduction to Ada” course, especially the Arrays chapter’s “Predefined array type: String” snippets and their build messages. Review how these snippets are compiled, including the reported Ada.Text_IO references and -gnatwU suggestion; the work is done when the course examples no longer produce distracting warnings unrelated to their explanations.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100