Documentation: optional didactic "Implementation Details" section

[expikr]

I think it would be nice if the wiki of some of the love.graphics functions can describe what functionalities of the underlying graphic API is used, making no guarantee for the stability of the described implementation detail; it's only for the purpose of learners getting a lay-of-the-land sense for what tools are available if they wish to graduate onto graphics programming directly.

And for the SDL functions used as well, Love2D being one giant example of how to use the library in an organized manner.

It's also useful for tinkerers experimenting with hacking into the underlying framework directly.

These should not be intended to be comprehensive, rather just providing "neat tidbits/trivia" wherever is appropriate or useful.

[a13X-B]

that's not the purpose of the wiki.
if you have any questions about using löve it would more appropriate if you brought them up on the forums/discord first

[expikr]

You misunderstood, I don't mean it as answering specific questions about love2d.

Rather, I'm suggesting that an in-place footnote of how the features are implemented specific to the subject of the page could do wonders for an "aha, so this is what I can use if I want to spin my own version of this feature" moment.

The majority of pages would not be appropriate to have such a section, it would only be for relatively involved functionalities dealing with the underlying framework.

[a13X-B]

that sounds like answering specific questions though. that would also clutter api with unrelated and confusing to a newconer info.
if you want to know how function implemented the source code is readily available. I still insist we move this discussion to forums/discord before rising an issue

[expikr]

You misunderstood, this is not a specific question for myself about how love2d works.

This is a general suggestion for a potential improvement to the documentation, which you may disagree with arguments, but is nonetheless precisely what Issues are meant for -- it pertains directly to a suggested alteration of the project, not an inquiry for how to use the project.

An in-place footnote, included sparingly, can also greatly compliment reading the source code, communicating high-level considerations of the implementation.

[MikuAuahDark]

We only guarantee consistent behavior across different graphics renderer unless noted (one such exception is love.graphics.setWireframe). For example, we guarantee that love.graphics.rectangle("fill", 100, 100, 100, 100) draws solid 100x100 pixels rectangle at X=100 Y=100 regardless of what graphics API LOVE uses. This is also true for the upcoming version with the introduction of Metal and Vulkan renderer, we guarantee the same behavior when Metal or Vulkan renderer is used.

We don't (and won't) have any documentation on how it's implemented because the underlying C++ code can change at anytime, including across minor versions. One case of this is the OpenGL code for drawing Canvas was changed significantly between 11.3 and 11.4 to workaround crashes in Intel driver stack in Windows.

[expikr]

I thought I made it quite clear with

making no guarantee for the stability of the described implementation detail; it's only for the purpose of learners getting a lay-of-the-land sense for what tools are available if they wish to graduate onto graphics programming directly.

and my deliberate use of the phrase “Implementation Detail” specifically to emphasize the lack of guarantee, that this is only for a purely supplementary footnote that is expected to be in flux, that compliments directly reading the source code by illuminating how the design decisions came to be.

[MikuAuahDark]

Then we would suggest them to read the LOVE source code instead.

[slime73]

That would be a lot of additional documentation work on top of what has to be done now (which is already a lot), and love's implementation may change without the API changing.

The best place to see how love works is by looking at love's source code, I think the extra documentation suggested is a little redundant compared to that. If there are specific questions about a particular part, community discussions like the forums or subreddit or discord server (but not the issue tracker) are a good place to ask.

[expikr]

You misunderstood, I am not saying to add a new section to every single page.

I'm saying to permit an optional behind-the-scenes scratchpad whenever it occurs to you that a particular function had an interesting implementation history or consideration, such as what one of the above replies cited -- those are precisely the kind of illuminating history that paints a picture of why certain design decisions are made, which greatly compliments reading the source code at the same time.

This optional "trivia" section, appended on an as-it-occurs-to-you basis, imposes no additional work beyond the whims of "oh, I remember this part, let me add a short footnote of a caveat of the GL function I had to deal with for this."

I made it quite clear that it is not meant to be comprehensive, only supplementary, so there is no expectation that they need to be monitored constantly.

[slime73]

You misunderstood

I understood, and I don't feel like it's a good use of our time.

[expikr]

I do not understand, what is the time consumed by "if you thought of a tidbit, feel free to throw it in, if it suits you"?

This is not proposing to immediately start scanning all the wiki pages and diligently writing supplementary notes. It is only a removal of a restraint, without any obligation associated.

I do not insist on the idea, but I only expect it was heard correctly and rejected at your judgement call rather than by misinterpretation, that is all.

[slime73]

Because that's extra work, especially to make a clear, concise, accurate, and relevant tidbit. It also adds noise to the wiki pages for anyone who doesn't find them relevant, so it'd be important to make sure they're as relevant and concise as possible.

I only expect it was heard correctly and rejected at your judgement call rather than by misinterpretation

I think you can/should assume this by default.