I see there's a few ways to report on problems and errors in the API, but I'm not clear on all of them and I think some may be missing. I propose either a sticky in the forum or a section in the Trac outlining these. Being really clear about them would help developers decide to implement them more easily.
The way I see it, the following need a way to be reported. Some already do.
User Experience
-Rating (SubtitlesVote)
-Text Comment (AddComment)
-Subtitle is for hearing impaired
Subtitle should be removed/banned, uploader notified
-Subtitle is machine-translated
-Subtitle format is broken/bad (covers also incomplete subtitles or with weird taggings)
Data should be unlinked
-Language is incorrect (infrequent but happens when autodetection misses, would unlink the subtitle from that language and re-do autodetection on it)
-Subtitle is not for this movie (currently covered halfway by ReportWrongMovieHash and ReportWrongImdbMovie, could be much better)
Internally in OS this comment should have different treatments, depending on where it comes from:
- If it comes from a moviehash search, then the subtitle should be unlinked and other subs with the same imdbid along with it.
- If it comes from an imdb search, then the subtitle should be unlinked and other subs with the same moviehash along with it.
- If it comes from a text search, then there's not a lot that can be done
Additionally, I believe AddRequest should have a "CheckRequests" counterpart, where past requests can be checked. This way the programs can keep track of previously requested subs in a single call and get the files without having to query for them periodically.
AddRequest(checkmoviehash,sublanguageid, optional user_note) and AddRequest(imdbid,sublanguageid, optional user_note): add to the queue
CheckRequests: displays the current queue with IDs and parameters
CleanRequest(parameters): removes a single item from the queue (when a sub has been downloaded for it) using the same parameters for requesting it or the ID from CheckRequests
The user_note in the AddRequest would be used for the client's benefit. For example, to store a local path.