current community

your communities

more stack exchange communities

company blog
Stack Exchange Inbox Reputation and Badges
tour help
up vote -1 down vote favorite

Today I was browsing Some of the official Android documentation. I came across the onOverScrolled method:

enter image description here

Like much of the official documentation describing class methods, the description over there is very terse. After reading it I still have very little idea of what it is used for, much less how to use it. There are no examples at all.

I wish I could go over to the Stack Overflow Android Documentation and check out the entry for onOverScrolled. What do all of those parameter names mean? How is it used in a practical example?

With the current setup I guess someone could create a new topic for onOverScrolled, but does such a small subject deserve its own topic? Wouldn't we be overrun with topics? Adding it to an existing topic doesn't work because of the example number limit.

These are just my thoughts for the day.

Notes

share
1  
I was completely mislead by the prepositions. 'Here' when posting on SO arguably refers to the stack overflow site, whereas you seem to mean that the documentation is very terse on the android documentation site. – Félix Gagnon-Grenier 12 hours ago
2  
Currently 940 thousand Android questions... I think we could probably stand to have a few more topics. A lot more topics. – Shog9♦ 8 hours ago
    
@Shog9, I guess I misunderstood documentation topics. So it would be ok to have a topic for something as small as onOverScrolled? – Suragch 8 hours ago
    
Sure. If there's a need, then why not? – Shog9♦ 8 hours ago
    
@Shog9, good to know. Since everyone created such large topics in the beginning, I assumed that was how it was supposed to work. This gives me more hope for Documentation now. Test case here. – Suragch 8 hours ago
1  
While I don't know the Android API, in most other frameworks, this kind of thing is documented at a higher level so that it doesn't have to be repeated for each individual method. You read the conceptual documentation to see how the API works in spirit, and then you apply that knowledge to the individual methods. In this case, onOverScrolled smells a lot like an overridable event handler, and anyone who understands how event-based programming models work is going to understand immediately how to use this. Otherwise, the parameter descriptions are terse, but seem quite complete. – Cody Gray 7 hours ago
    
@CodyGray, If it is documented at some higher level, it is certainly not obvious where to find that documentation or how to apply it in this instance. Even if the descriptions here are complete enough for the original documenters and expert programmers, how do people like me find more explanation and examples, especially if SO.Documentation takes the stance that such minuscule methods should not get their own topic? – Suragch 6 hours ago
    
Well, you're right that most library documentation is not designed for copy-paste programmers. The docs for specific functions are intended more as a quick reference for people who are already familiar with the library/API and its idioms. So in answer to your question of where you find that documentation, I would say that you start reading at the "Introduction" and continue through until you have the necessary conceptual understanding. At least, this is how Microsoft's documentation on MSDN works, as well as Qt, and every other library I'm familiar with. SO may want a different model, though. – Cody Gray 6 hours ago
    
It would probably be better to have an "Events" Topic with examples for each events. – Walfrat 5 hours ago
    
@Walfrat, the limit on the number of examples would be a hindrance to that. – Suragch 5 hours ago

You must log in to answer this question.

Browse other questions tagged .