Hello, everyone!
I have some detailed questions on documentations,
1. should I put JavaDoc comments on private methods and instance variable?
2. what kind of comments did you put for the code? which should I use // or /* */?
3. shoule I comment on the deprecated methods, or only just need to delete the old one?
4. how did you make the javaDoc comments on the DataInterface, just copy it from Data and no comments on the LocalData and RemoteData?
5. continue with item 4, if i use LockManager, there is also lock method, should I comment it the same as Data?
6. How to comment a method which is composed by some other methods, for example,
public void lock(int recno) {
if(recno == -1) lockDatabase();
else lockRecord();
}
because the functional descriptions are already in the lockDatabase() and lockRecord, if I comment them again in the lock, is that redundant?
7. Did you modify the comments in Data class which has some obvious comment error, for ext.,
in lock comment, there is @param recno, but the actual argument for lock is lock(int record).
8. if I don't implement lock/unlock in the Data class, leaving the methods empty, should I change the JavaDoc comments that already there, or just don't care?
sorry for bring up so many trivial questions, but I think it is a good chance for us to learn documentation.
thanks!