IssueTracker

In short

On the page https://developer.android.com/topic/libraries/architecture/datastore it is not clear where to create the DataStore and there's further confusion about files.

Snippets

Create a Preferences DataStore

Use [...] to create an instance of Datastore<Preferences>. Call it once at the top level of your kotlin file, and access it through this property throughout the rest of your application.

(BTW, "in the kotlin file" is mentioned in 2 places on this page)

There's also a reference to a file elsewhere on the page:

Never create more than one instance of DataStore for a given file in the same process.

Detailed description

What files are we talking about?

DataStore file

I assume the DataStore is backed up by a file, and that's the "given file"? But this concept of a DataStore representing an underlying file isn't explained in the introduction.

"The kotlin file"

I have many kotlin files. Apparently we're talking about a singleton instance. Does it matter which kotlin file to create this in? In some other documentation (a code lab on DataStore) it says

To create a DataStore instance we use the preferencesDataStore delegate, with the Context as receiver. For simplicity, in this codelab, let's do this in TasksActivity

This seems to suggest that it's ok if you have one activity, but not recommended. So, what do I do in a bigger project?

In the worst case, this all could be wrongly interpreted as that you "may only create a DataStore once in every kotline file" I'm pretty sure that is not what is meant.

Suggestion

Make it clear what files we're talking about and where it's ok to create the DataStore. Clearly explain different possibilities to instanciate a DataStore. For example, I noticed that the now-in-android app seems to inject the DataStore via Hilt, so that seems to be a possibility.