{"action":"created","issue":{"url":"https://api.github.com/repos/dotnet/core-docs/issues/772","repository_url":"https://api.github.com/repos/dotnet/core-docs","labels_url":"https://api.github.com/repos/dotnet/core-docs/issues/772/labels{/name}","comments_url":"https://api.github.com/repos/dotnet/core-docs/issues/772/comments","events_url":"https://api.github.com/repos/dotnet/core-docs/issues/772/events","html_url":"https://github.com/dotnet/core-docs/issues/772","id":164455665,"number":772,"title":"Add API Docs for .NET","user":{"login":"richlander","id":2608468,"avatar_url":"https://avatars.githubusercontent.com/u/2608468?v=3","gravatar_id":"","url":"https://api.github.com/users/richlander","html_url":"https://github.com/richlander","followers_url":"https://api.github.com/users/richlander/followers","following_url":"https://api.github.com/users/richlander/following{/other_user}","gists_url":"https://api.github.com/users/richlander/gists{/gist_id}","starred_url":"https://api.github.com/users/richlander/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/richlander/subscriptions","organizations_url":"https://api.github.com/users/richlander/orgs","repos_url":"https://api.github.com/users/richlander/repos","events_url":"https://api.github.com/users/richlander/events{/privacy}","received_events_url":"https://api.github.com/users/richlander/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":14,"created_at":"2016-07-08T04:10:36Z","updated_at":"2016-07-09T23:54:39Z","closed_at":null,"body":"# Proposal for API Docs\r\n\r\nAPI documentation is important! We need to define the following:\r\n\r\n- The user experience of viewing documentation.\r\n- How the content will be structured.\r\n\r\nSee existing docs and content: https://docs.microsoft.com/en-us/dotnet/core/api/system.\r\n\r\n## Requirements\r\n\r\n- The docs will represent multiple .NET products.\r\n- There must be good UX for navigating and filtering across the products.\r\n- The content will be open source and be moved to a single location (core-docs).\r\n\r\n## Assumptions\r\n\r\nThe APIs are the same across all products, including implemented interfaces and class inheritance. In some cases, this won't be true. If it's an exception, we'll decide that one implementation is the default and any others are correctly described in remarks.\r\n\r\n## Scope\r\n\r\nThe docs will document .NET APIs in: \r\n\r\nFrameworks:\r\n\r\n- .NET Core (including for UWP)\r\n- .NET Framework\r\n- .NET Standard \r\n- Mono\r\n\r\nLibraries:\r\n\r\n- ASP.NET / Core\r\n- EF\r\n- NuGet\r\n\r\n## UX\r\n\r\nThe user experience should bias towards seeing all APIs while providing soft-filters and cues to define which APIs are implemented in the various products. This is primarily an issue for the frameworks listed above, as opposed to the libraries.\r\n\r\n### Representation\r\n\r\n- One canonical representation per API (e.g. one page for System.String type; not one for Mono and one for .NET Framework).\r\n- Remarks will discuss product specific behavior, as appropriate.\r\n\r\n## URLS\r\n\r\nURLs are easy to predict and hack.\r\n\r\n   - https://docs.microsoft.com/en-us/dotnet/api/system\r\n   - https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.list-1\r\n\r\nHacking means that the following URLs should go somewhere useful:\r\n\r\n- https://docs.microsoft.com/en-us/dotnet/api\r\n- https://docs.microsoft.com/en-us/dotnet/api/system\r\n- https://docs.microsoft.com/en-us/dotnet/api/system.collections\r\n- https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic\r\n\r\n### API Version Filtering \r\n\r\nThe default experience is viewing all .NET APIs, unfiltered by product or release. You can filter your view in terms of a product and version, such as .NET Framework 4.5, .NET Standard 1.5 or Mono 4.4. \r\n\r\nGood example of version navigation: https://developer.android.com/reference/packages.html. The Android experience always shows all APIs and greys some of them out. That's a great experience. The \"Platform\" toggle on this page is not a good experience: https://docs.microsoft.com/en-us/active-directory/adal/microsoft.identitymodel.clients.activedirectory. \r\n\r\n### Describing Product Membership\r\n\r\nThe unfiltered view states all .NET products that support a given type/member, independent of filter. For example, when viewing pages in terms of Mono, you see \"Introduced in Mono 1.1, .NET Framework 2.0, ...\".\r\n\r\nTwo options for the filtered view:\r\n\r\n- Same as the unfiltered view.\r\n- State the \"Introduced in\" only for the filtered product (e.g. \"Introduced in Mono 1.1\" when viewing in terms of Mono 4.4 or Mono latest).\r\n\r\n### View Source\r\n\r\nThe \"View source\" should take you to the product source for a given type or member. It should take you to the specific product in the filtered view and a default product in the unfiltered view.\r\n\r\nProduct version is not important for this experience, only product.\r\n\r\nExamples, for the Filtered case:\r\n\r\n- .NET Core: use CoreFX repo.\r\n- Mono: use Mono repo\r\n- .NET Framework: use referencesource repo or http://sourceof.net\r\n\r\nFor unfiltered, use a precedence algorithm, based on API availability information from reference assemblies:\r\n\r\n- corefx\r\n- referencesource\r\n- mono\r\n\r\n### Improve this Doc\r\n\r\nAssumption: All docs are in the core-docs repo.\r\n\r\nThere are two ways to improve a document, either via updating the .cs file or the sidecar file. The \"Improve this doc\" button can only go to one place. Both files should contain a fully-qualified GitHub link to the other file (in a comment), so that it's easy to go from one file to the other.\r\n\r\nProposal: The button takes you to the .cs file. It's an open question of whether it should be in \"edit\" or \"view\" mode on GitHub.\r\n\r\n\r\n\r\n## Format\r\n\r\n- /// comments in .cs files, one file per type\r\n- The .cs files are skeletal versions of types, much like: https://github.com/dotnet/corefx/blob/master/src/System.Collections/ref/System.Collections.cs\r\n- Remarks are in a sidecar file, one per type.\r\n- These files include APIs for the union of all .NET products, enabling all .NET APIs to be documented.\r\n- No decoration of types or members in these files for .NET product membership (e.g. part of .NET Framework 4.5.1). We can query reference assemblies for that.\r\n\r\n## File structure\r\n\r\n- Flat structure under: https://github.com/dotnet/core-docs/tree/master/api\r\n- Example: https://github.com/dotnet/core-docs/tree/master/api/system.collections.generic\r\n\r\n## Versioning\r\n\r\nThe repository does not version, in terms of branching. There will not be branches for given .NET product releases. It's certainly fine to branch as part of a release, but the branch will be temporary. Given that the repository is for multiple products, the branches would not be meaningful / intuitive.\r\n\r\n## Relationship to Product Source\r\n\r\n/// comments will be copied to product source on some cadence. One option is to snapshot /// comments from core-docs into corefx (for example) once per release, at the start of the release. This means that /// comments in product source will always be one release behind, but also won't disrupt product source at an unfortunate time.\r\n\r\n## Adding new APIs\r\n\r\nThere needs to be a tool that can take a set of reference assemblies and then add new APIs into the .cs files that are not present as stubs (empty /// comments).\r\n\r\nExtra effort: A tool that prints out types and members that are missing /// comments.\r\n\r\n## Projects that already have /// comments\r\n\r\nProjects (basically all the libraries) like ASP.NET Core already have /// comments within the product source. They don't have to change what they are doing. \r\n\r\nIn those cases, \"View Source\" and \"Improve this Doc\" will go to the same place, to the product source. \r\n\r\nWe need to decide for these projects where the sidecar files will go. Ideally, they'll go in the product repo, beside the files, potentially in a subdirectory. There isn't much value in splitting this content and requiring contributors for that content to clone two repos.\r\n\r\n## IntelliSense\r\n\r\nIntelliSense will need to be generated from these same files. We'll need a similar tool that generates intellisense files from the .cs files plus a set of reference assemblies that defines a given platform.\r\n"},"comment":{"url":"https://api.github.com/repos/dotnet/core-docs/issues/comments/231562327","html_url":"https://github.com/dotnet/core-docs/issues/772#issuecomment-231562327","issue_url":"https://api.github.com/repos/dotnet/core-docs/issues/772","id":231562327,"user":{"login":"richlander","id":2608468,"avatar_url":"https://avatars.githubusercontent.com/u/2608468?v=3","gravatar_id":"","url":"https://api.github.com/users/richlander","html_url":"https://github.com/richlander","followers_url":"https://api.github.com/users/richlander/followers","following_url":"https://api.github.com/users/richlander/following{/other_user}","gists_url":"https://api.github.com/users/richlander/gists{/gist_id}","starred_url":"https://api.github.com/users/richlander/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/richlander/subscriptions","organizations_url":"https://api.github.com/users/richlander/orgs","repos_url":"https://api.github.com/users/richlander/repos","events_url":"https://api.github.com/users/richlander/events{/privacy}","received_events_url":"https://api.github.com/users/richlander/received_events","type":"User","site_admin":false},"created_at":"2016-07-09T23:54:39Z","updated_at":"2016-07-09T23:54:39Z","body":"Thanks for sharing your insight. I've not done your job before, so I'll take what you say at face value, and of course, respectfully, as you hope.\r\n\r\nWe've now traveled a ways away from the topic of this issue, so I think I'll not go any farther into this topic, as much as I do think it is an interesting one to discuss further. Given that we now work for the same company, I think we'll indeed have the option available to us."}}
{"actor":{"display_login":"richlander"}}