Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Microsoft"Docs" is not worth it's Name - it's a shame, what Microsoft creates (generates?) #1512

Closed
schittli opened this issue May 20, 2019 · 3 comments

Comments

Projects
None yet
4 participants
@schittli
Copy link

commented May 20, 2019

The bug
While Micorosft is proud to present its exorbitant profits to the world, we can watch the product quality degenerate. For example, more and more documentation is reduced to its minimum as if a stupid document generator would generate it.

The result:
As developers who still support the M$ platform, we miss the professional documentation more and more often.

To Reproduce
Let's see that we can do by using DWMWA_EXTENDED_FRAME_BOUNDS:

  1. Open Microsoft"Docs" for DwmGetWindowAttribute function
  2. OK, we must navigate to Microsoft"Docs" for dwAttribute
  3. Try to understand what e.g. DWMWA_EXTENDED_FRAME_BOUNDS is doing. Some most basic and usual questions:
  • What is returned in dwAttribute, pvAttribute and cbAttribute?
  • What's the issue if pvAttribute sometimes returns the (wrong) x coordinate of -32000?
  • Is it a bug or an undocumented error code?
    If it's a bug, then it's sad for M$ because you'll get the bug reported too late, because the expected behavior is not documented.
    If it's an undocumented error code, then it's sad for M$ because your developers (which are writing Software for your platform) realize that Microsoft is trampling on their needs.

Expected behavior
A clear and concise description of all functions

Desktop (please complete the following information):
(everything in docs.microsoft.com)

@ryanmajidi

This comment has been minimized.

Copy link
Collaborator

commented May 20, 2019

@GrantMeStrength Can you please take a look at this issue?

@stevewhims

This comment has been minimized.

Copy link
Member

commented May 31, 2019

UPDATED

Hi, @schittli, thanks for filing this GitHub issue; and my apologies for the issues themselves and my delay in responding. I'll describe the steps I've taken so far to address the issues, and the question that remains.

First, I update the conceptual topic Enable and control DWM composition to make it clear what the relationship is between a) the attribute flag passed to DwmGetWindowAttribute and DwmSetWindowAttribute, and b) the type of the attribute value that those functions retrieve/set. I added more code examples to that topic, include specifically a code example for DWMWA_EXTENDED_FRAME_BOUNDS, which was a scenario that you mentioned.

Next, I went through the three API reference topics below, and made sure the descriptions of each of the parameters/fields was clear, and I added a very prominent link (at the beginning of each of these three API ref topics) to the conceptual topic, so that readers would know from the start that code examples (and conceptual content) exist, and where to find them.

For the -32000 value that you mentioned, I also updated the third topic above, in the table row for DWMWA_EXTENDED_FRAME_BOUNDS, and I added this content, "If the window is minimized or otherwise not visible to the user, then the value of the RECT retrieved is undefined. You should check whether the retrieved RECT contains a boundary that you can work with, and if it doesn't then you can conclude that the window is minimized or otherwise not visible." I feel like that's a robust way of dealing with corner cases rather than checking for specific constant value, which it's safe to think of as implementation details.

Thanks!
Steve

@stevewhims stevewhims added the content label May 31, 2019

@stevewhims

This comment has been minimized.

Copy link
Member

commented Jun 4, 2019

Hi, @schittli, I've gone ahead and resolved the issues that you found. I've detailed my fixes above. I'll go ahead and close this issue now, since it feels resolved. But please re-open it, or file news one, if necessary.

Thanks!
Steve

@stevewhims stevewhims closed this Jun 4, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.