Is there a way to specify in Java docs that a method should be called from a non-UI thread

Question

I was writing a set of functions for accessing/writing data to the SQLite database in my android application. Since I need to use getWritableDatabase() to get the database instance and this needs to be called in a non-UI thread, I was wondering if there a clean way to specify the same warning in the java docs of these functions?

Also, I needed one more clarification about getting handle over the database instance using getWritableDatabase(). I should call this wherever I need to write things into database right? Or can I call this once at the application level and use the same handle to access db at different places in the app?

You are actually asking two very different things here. I suggest that you rather split up this question and create another one for the second paragraph. — GhostCat, Mar 29 '17 at 06:10

score 1 · Answer 1 · answered Mar 29 '17 at 06:09

There are no fixed rules for such things. You can only rely on conventions/style.

In other words: try to come up with explicit, unambiguous wording and make sure that this part is easy to read and quick to spot in your javadoc (check the generated HTML as well for these properties).

And then be prepared for bug reports from people ignoring your javadoc.

score 1 · Answer 2 · edited May 23 '17 at 12:17

1

Rather than just leaving a warning in the javadoc, you might add validation, i.e. detect if you're on the UI thread (see How to check if current thread is not main thread), then throw an exception.

Document that exception.

edited May 23 '17 at 12:17

Community

1
1

answered Mar 29 '17 at 06:18

Andreas

154,647
11
152
247

Is there a way to specify in Java docs that a method should be called from a non-UI thread

2 Answers2