Add comment to core

The main goal of this PR is to ensure that all strings get a
comment. While I used to naively think that most string were clear,
and that translators would be able to figure out what they were
translating, I realized, looking at the French translation, that it's
not actually the case.

Instead of just fixing the French translation, I prefer to improve the
process so that AnkiDroid can be correctly translated in all
languages.

In particular, some strings are used in multiple context. E.g. as a
button and the title of the dialog/view opened by this button. In
English, it's certainly correct. In French it usually is too. I have
no idea whether it's correct in all other languages. By letting the
translators know that the strings is used in both context, they can
provide feedback if ever they need us to split the string in two.

As an example, I recently split "Search" in two strings, one for the
verb and one for the noun "search", because, in French, we need to use
distinct words to consider the search action, and the content of the
search request.

I should note that this task requires to look at all the strings, and
look for all its usage in the codebase. Which means this task can only
be done by a developer that knows the codebase and the app enough to
understand all usages of each string. Worse, either reviewing
such changes will be very painful, or the reviewer will have to have a
high trust in the person doing this work. Which means, and I'm quite sad
about it, that it can't really be delegated.

As requested by David, I'm not adding every usage in the comment. But
at least, if something is both a title and a button, I indicate that
it can be used as different kind of object. Both an information and a
call to action.

As a secondary goal, the commit reorders the string, so that they
strings appearing in the same view get shown together. This is not
probably not important for translators, but I find it cleaner.

I also add new line if when there is a comment to ensure the lines are
not absurdly long.

I don't exactly expect this PR to be merged as-is. I mostly open it to
gather feedback. If you are against this change (e.g. because it'll
destroy the history of all our string files), I can stop and not spend
more time on it.

Or, if you have any idea of a better way to write comment, I can use
your idea in the future comments.

Once we agree this work is worthwhile and can eventually be merged, if
you find typos, gramattical errors, or general improvement, I'd
appreciate if you could directly push the correction as an additional
commit, or provide the correction as a suggestion in github review
system. Because, discussing every comment individually would be a
nightmare of bikeshedding

Author: Arthur-Milchior

AnkiDroid/src/main/res/values/01-core.xml

@@ -20,48 +20,56 @@
 -->
 <resources xmlns:tools="http://schemas.android.com/tools">
     <!-- Navigation drawer items-->
-    <string name="decks" maxLength="28">Decks</string>
-    <string name="card_browser" maxLength="28" comment="The usage of card browser inside the app (note the casing)">Card browser</string>
-    <string name="statistics" maxLength="28">Statistics</string>
-    <string name="settings" maxLength="28">Settings</string>
-    <string name="help" maxLength="28">Help</string>
-    <string name="drawing">Drawing</string>
-    <string name="send_feedback">Send feedback</string>
+    <string name="decks" maxLength="28" comment="Open the Deck Picker">Decks</string>
+    <string name="card_browser" maxLength="28" comment="Title of the Card Browser, and button to open it.">Card browser</string>
+    <string name="statistics" maxLength="28" comment="Title of the Statistics page and button to open it.">Statistics</string>
+    <string name="settings" maxLength="28" comment="Title of the Settings page, and button to open it.">Settings</string>
+    <string name="help" maxLength="28" comment="Title of the help menu and button to open it.">Help</string>
+    <!-- The last entry "Support ankidroid" is in 03-dialogs.-->
 
-    <string name="studyoptions_start">Study</string>
+    <!-- Entries of the "attach" in the "add card" view. -->
+    <string name="drawing" comment="Menu entry to create a drawing to attach to a card. Also a title.">Drawing</string>
+
+    <!-- Entries of the Support ankidroid menu. -->
+    <string name="send_feedback" comment="Menu entry in the 'Help>Support ankidroid' menu, that opens the web page explaining how to send feedback.">Send feedback</string>
+
+    <!-- Study Options-->
+    <string name="studyoptions_start" comment="Title of the Reviewer activity. Also the button to open it.">Study</string>
 
     <!-- DeckPicker.kt -->
-    <string name="expand">Expand</string>
-    <string name="collapse">Collapse</string>
-    <plurals name="reviewer_window_title">
+    <string name="expand" comment="In the deck picker: accessibility label of the buttons that display the subdecks of a deck.">Expand</string>
+    <string name="collapse" comment="In the deck picker: accessibility label of the buttons that hide the subdecks of a deck.">Collapse</string>
+    <string name="menu_import" comment="Title of the import page and the button to open it." maxLength="28">Import</string>
+    <string name="no_cards_placeholder_title" comment="Text shown the first time AnkiDroid is opened, to explain to the user why they can't yet review.">Collection is empty</string>
+    <string name="no_cards_placeholder_description" comment="Text shown the first time AnkiDroid is opened, to explain what should be their first action.">Start adding cards\nusing the + icon.</string>
+
+    <!-- Reviewer -->
+    <plurals name="reviewer_window_title" comment="Header of the reviewer, telling the users how many minutes remains before they have seen all cards.">
         <item quantity="one">%d minute left</item>
         <item quantity="other">%d minutes left</item>
     </plurals>
-    <plurals name="reviewer_window_title_hours_new">
+    <plurals name="reviewer_window_title_hours_new" comment="Header of the reviewer, telling the users how many minutes remains before they have seen all cards. The second parameter is the number of minutes.">
         <item quantity="one">%1$d hour %2$d left</item>
         <item quantity="other">%1$d hours %2$d left</item>
     </plurals>
-    <plurals name="reviewer_window_title_days_new">
+    <plurals name="reviewer_window_title_days_new" comment="Header of the reviewer, telling the users how many minutes remains before they have seen all cards. The second parameter is the number of hours.">
         <item quantity="one">%1$d day %2$dh left</item>
         <item quantity="other">%1$d days %2$dh left</item>
     </plurals>
-    <string name="no_cards_placeholder_title">Collection is empty</string>
-    <string name="no_cards_placeholder_description">Start adding cards\nusing the + icon.</string>
-
-    <!-- The deck picker via AnkiStatsTaskHandler.java -->
+    <string name="type_answer_hint" comment="In the reviewer. When the user use note type with hint. It's the default content of the text field in which the user is invited to type their answer. It disappears as soon as the user start to type.">Type answer</string>
+    <string name="show_answer" maxLength="41" comment="When displaying the question side of a card. This is the label of a button that display the answer side.">Show answer</string>
+    <string name="hide_answer" comment="In the previewer, when the answer side is displayed. This is the label of the button that sends back to the question side.">Hide answer</string>
+    <string name="ease_button_again" maxLength="41" comment="In the reviewer, in the answer side. Label of the button that request the card to be shown again soon.">Again</string>
+    <string name="ease_button_hard" maxLength="41" comment="In the reviewer, in the answer side. Label of the button that used by the user to state finding the correct answer was hard.">Hard</string>
+    <string name="ease_button_good" maxLength="41" comment="In the reviewer, in the answer side. Label of the button that used by the user to state their answer was good.">Good</string>
+    <string name="ease_button_easy" maxLength="41" comment="In the reviewer, in the answer side. Label of the button that used by the user to state that finding the answer to the question was easy.">Easy</string>
+
+    <!-- General -->
+    <string name="undo" maxLength="28" comment="When tapping on this text, the last action is undone.">Undo</string>
+    <string name="redo" maxLength="28" comment="Menu entry that allows to redo action that was just undone.">Redo</string>
 
 
     <!-- flashcard_portrait.xml -->
-    <string name="type_answer_hint">Type answer</string>
-    <string name="show_answer" maxLength="41">Show answer</string>
-    <string name="hide_answer">Hide answer</string>
-    <string name="ease_button_again" maxLength="41">Again</string>
-    <string name="ease_button_hard" maxLength="41">Hard</string>
-    <string name="ease_button_good" maxLength="41">Good</string>
-    <string name="ease_button_easy">Easy</string>
-    <string name="menu_import" maxLength="28">Import</string>
-    <string name="undo" maxLength="28" comment="When tapping on this text, the last action is undone.">Undo</string>
-    <string name="redo" maxLength="28">Redo</string>
     <string name="undo_action_whiteboard_last_stroke" comment="One of the display patterns of 'Undo' item on the action menu in Reviewer. It is shown as the title of the item when the whiteboard (handwriting) feature is enabled and visible and has any strokes (handwritten lines)" maxLength="28">Undo stroke</string>
     <string name="move_all_to_deck">Move all to deck</string>
     <string name="unbury" maxLength="28">Unbury</string>
@@ -190,11 +198,11 @@
     <string name="storage_access_title">Storage access</string>
     <string name="storage_access_summary">Saves your collection in a safe place that will not be deleted if the app is uninstalled</string>
     <string name="all_files_access_title"
-        comment="Name of the “All files access” permission from Android 10 and after">All files access</string>
+        comment="Name of the “All files access” permission from Android 10 and after. See [android.permission.MANAGE_EXTERNAL_STORAGE] on https://developer.android.com/training/data-storage/manage-all-files for context.">All files access</string>
     <string name="image_occlusion">Image Occlusion</string>
 
     <string name="remove_account" comment="open a website to start the deletion of an AnkiWeb account">Remove account</string>
 
     <!-- Instant Note Editor -->
-    <string name="instant_card" comment="This does not need to be translated literally, translate the concept of quickly adding a Cloze note with a popup. Used in the Android system context menu/share dialog.">Instant card</string>
+    <string name="instant_card" comment="Used in the Android system context menu/share dialog to quickly create a note. This does not need to be translated literally, translate the concept of quickly adding a Cloze note with a popup. ">Instant card</string>
 </resources>