Fair points. As a counter-point, though, Simulink's integrate block works exactly as you'd expect an "integrate" block to work.
I don't expect the GR documentation to explain the fundamentals of a generalized block (any IIR filter) but it would be nice if they explained what the specific implementation does (GR's IIR filter). In general I have found that most blocks don't even say what the parameters do, or really explain what the output of a block is. Just as an example of the difficulty a user faces, though, look at the IIR filter "Old style of taps" parameter description:
"The old style of the IIR filter uses feedback taps that are negative of
what most definitions use (scipy and Matlab among them). This parameter
keeps using the old GNU Radio style and is set to TRUE by default. When
taps generated from scipy, Matlab, or gr_filter_design, use the new
style by setting this to FALSE."
This doesn't tell me what GR's tap definition is... just how it compares to other tools. To use the GR IIR filter block I need to know how the equivalent element works in scipy or Matlab. It would be very nice if there was an actual description of what the filter taps field is, more than what it is not. Imagine if LibreOffice Calc's documentation described a function as "the same as what's implemented in Excel, except parameter B is the negative of what it is in Excel", with no further explanation. If you're not versed in Excel then such a description has no value to you.
I've actually been using GR for a long time (although, again, not a DSP expert), but 99% of what I do is in OOT modules. The built-in blocks often have fundamental oddities in their behavior that makes them less useful than they otherwise might be. It's not a criticism, just a comment that I hope is constructive, since developers may not have the understanding of a user's perspective. I have a few thousand hours working with GR over 5+ years and written dozens of blocks, so I understand its value, and am grateful for that. But even with the time I have invested in it, I still find it incredibly non-intuitive. For me, the power of GR is its infrastructure, e.g., the scheduler, handling data streams, message passing, the GRC framework for quick and dirty testing, and so on. I've generally found it quicker to write my own block than try to understand what the built-in blocks actually do!!
Joe