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

OS dependent based API documentation should be marked. #130

Open
glennawatson opened this issue Aug 3, 2018 · 1 comment
Open

OS dependent based API documentation should be marked. #130

glennawatson opened this issue Aug 3, 2018 · 1 comment

Comments

@glennawatson
Copy link
Contributor

A user posted a stack overflow https://stackoverflow.com/questions/51667191/reactiveui-how-to-use-icollectionview-with-the-getting-started-example

The user got confused in WPF about the https://reactiveui.net/api/reactiveui/reactivecollectionviewsource_1/61104db4

He thought he should be using this in his WPF application but looking at the source code this is iOS only code.

We should clearly mark code if they are in the src/reactiveui/platforms folder to which platform they come form.

@daveaglick
Copy link
Member

Answering the question from @RLittlesII over in Wyam:

In ReactiveUI we have several API's that are specific to certain platforms. Does Wyam provide a way when generating the API documentation to categorize the API's to relevancy?

Example would be certain API's are relevant only in iOS or Android.

Not out of the box, no. That's a tough thing to get right because to Wyam, code is code is code. If Roslyn builds it and it ends up in the API docs, it's all the same. We'd need some way to say "this is iOS only" or "this is for all platforms".

Just quickly brainstorming, this might be doable with custom XML doc comments. Since those are picked up and exposed in the Wyam IDocument for each symbol, you could override the _ApiBeforeContent.cshtml file to show some sort of disclaimer depending on if the given XML doc comment is present on the symbol. For example, Cake overrides this file to show a disclaimer about being third-party here which displays this partial.

And actually, another way to do it would be to do something even more like what Cake is doing. Override the _ApiBeforeContent.cshtml file to check the symbol's namespace or assembly. If it matches one that's known to be just for a particular platform, display the appropriate disclaimer.

cc @ghuntley @onovotny

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants