Documenting kernel32.dart and friends

[domesticmouse]

Hey Tim,

To make it easier to explore win32, I'd like to add documentation to kernel32.dart (and the other APIs), but I'm guessing this file is autogenerated from somewhere. Can you give guidance on a viable path forward that I could start contributing to?

brett

[timsneath]

The COM and Windows Runtimes are automatically generated, but the traditional C-based APIs are artisanally crafted with love from Seattle :)

There's an intern project currently underway to experiment with automatic generation of C-based APIs, but there is a lot of complexity with Windows APIs (nested and union arrays, ANSI and UNICODE variants, dependencies across multiple header files and conditional imports), and I'm not taking it for granted that automatic generation will work here. Although I'd loved to be proven wrong.

Each API is a direct analog of the underlying Win32 API, so I'm assuming that users will rely on the Windows documentation. It is a shame that the parameter names don't come through from the typedef though, and I don't have a good solution to that.

I have started categorizing the entries so that dartdoc can produce custom pages for each library (see https://github.com/timsneath/win32/blob/master/dartdoc_options.yaml), but pub.dev doesn't seem to use the generated categories, although they do appear when I run dartdoc locally.

Interested in your thoughts here.

[domesticmouse]

What I'm hearing here is:

1. Feel free to go ahead with adding Dartdoc to the C-based API files, but be aware we might replace it later with some C header parsing doc generation magic, and
2. Hassle @jonasfj to add category support to Pub's documentation generation pipeline.

Is that a reasonable summary? =)

[jonasfj]

You can generate dartdoc and host it on GitHub pages... The put a link to it in pubspec.yaml using the documentation key. Then pub.dev will link to said docs on the package page.

This allows for custom documentation pages of all sorts.. there are still many things we don't quite support from dartdoc. Generally, we don't allow packages to ship custom dartdoc options because of security concerns.. but categories could perhaps be supported.

[timsneath]

Thanks :)

I've experimented with pushing dartdoc pages to gh-pages, which at least gives us category pages. I might take a look at updating https://github.com/a14n/dart-ghpages-generator to do this automatically. @domesticmouse, you might find this more consumable than the previous approach.

You're welcome to add further comments to the APIs, but without some automation I'd worry that the juice isn't worth the squeeze. I suspect more examples (or a higher-level API) is better value for money. I have added some library-level documentation (see, for example: https://timsneath.github.io/win32/win32/win32-library.html)

[jonasfj]

Having categories would be pretty neat, filed: dart-lang/pub-dev#3793

[timsneath]

I'm going to close this issue out based on our conversation and areas of focus last night, @domesticmouse. Feel free to reopen it if you disagree.

[domesticmouse]

sgtm!