Add Interoperability primer document #31
Conversation
There was a problem hiding this comment.
IMO it would be nice to follow same guildelines in samples https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/coding-style.md
There was a problem hiding this comment.
That's a good point. I think it would be valuable to go through the whole doc set and standardize the samples. Thoughts, @blackdwarf @richlander?
There was a problem hiding this comment.
Given the flux of stuff at this point, the samples might change, so going through them all in the entire doc set might be little too much work. We could do it for the primer, at least, since the topics there are unlikely to change.
There was a problem hiding this comment.
Ideally, and @blackdwarf and I were talking about this recently, we would not have any sample code in the source doc files themselves and just refer to samples elsewhere via a range link. As I recall, it is hard for Sphinx to refer to samples outside the repo.
Having the samples align with the corefx code guidelines is a good idea.
|
Added changes from the PR. Thanks for reviewing! |
docs/concepts/native-interop.rst
Outdated
There was a problem hiding this comment.
It is useful to state that the FX itself relies on native interop to implement FX APIS, such as for writing to the console and reading files.
There was a problem hiding this comment.
Good point that one, will add.
|
On COM Interop ... I'm still having trouble with that. I think we should remove it. It's true we want these docs to be general enough that someone using .NET Framework, Xamarin or Unity would take benefit from them. It also means that they shouldn't be confused by Windows only content. @migueldeicaza gave us the advice to approach the platform with a Unix-first mentality. I think that we need to apply that guidance as best we can. |
|
If you want, removing it is easy. I fear, however, that we are not giving a clear enough picture of the overall .NET possibilities. I agree with @migueldeicaza comment, it is the right way to go, but maybe I should just try to make the distinction even clearer (between COM interop and P/Invoke and what is supported where)? |
|
What's wrong with putting COM Interop as part of .NET Framework-specific section of this doc set and not mentioning it here? Put another way, if I'm reading this documentation to learn about .NET Core (I assume that's the primary scenario), how is COM Interop relevant to me, particularly if I'm reading this on an OS X machine? |
|
Errrr...We don't have a .NET Framework specific section of this doc set (that I know of). And the idea was (at least when we started) that you are new to .NET and reading the Primer to learn about .NET not specifically about .NET Core. If this is .NET Primer about Core only, then for sure, COM interop should not exist. |
|
OK, I've updated the document. Added Linux and OS X samples. I've also removed COM Interop from the document, in order to unblock the PR. I've also added comments to some code samples to see how it would work. |
|
Thanks for all the effort @blackdwarf. Let's go with that! Can you rebase and then merge? |
Blurb added to the Primer main document. Add more detailed document in the documents.
blackdwarf
force-pushed
the
netprimerwork
branch
from
edca2fd to
d213c58
Compare
|
Done, merging (finally). :)) |
Add Interoperability primer document
|
Thanks for all the effort @blackdwarf! |
Blurb added to the Primer main document. Add more detailed document
in the documents. The document covers both P/Invoke and COM interop. The COM interop doesn't have an example, which I left out intentionally, because I couldn't find a good one that would not branch off into other points like using dynamic etc.
/cc @richlander @terrajobst