Skip to content

Commit 53a0610

Browse files
rolfbjarnerolfbjarne
authored
[docs] Document how to update our api reference docs. Fixes #17401. (#24118)
Fixes #17401. Fixes #17396.
1 parent 0d596a4 commit 53a0610

File tree

4 files changed

+338
-0
lines changed

4 files changed

+338
-0
lines changed

‎docs/ReleaseCheckList.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ This happens after the stable version of Xcode has been released and the `xcodeX
6767
* [ ] Update https://github.com/dotnet/maui/wiki/Release-Versions
6868
* [ ] Update API diff (the `STABLE_NUGET_VERSION_*` variables in `Make.config`). Can only be done after the NuGets have been published to nuget.org.
6969
* [ ] Update docs by executing `docs/sync-mobile-docs.sh`. Beware if docs were modified in the [docs-mobile](https://github.com/dotnet/docs-mobile) repository by somebody else, any such changes will have to be copied back first.
70+
* [ ] Update API / reference docs. See [update-api-docs.md](/tree/main/docs/update-api-docs.md) for instructions.
7071
* [ ] Make sure all items in the milestone for the current release have been closed.
7172
* [ ] Close this issue & close the milestone.
7273
* [ ] Wonder about life as you consider the impossibility of actually reaching this point, because you can't close the milestone before all issues have been closed, and you can't close this issue until checking off all items, which you can't do until you've closed the milestone. Decide to schedule yet another viewing of [Life of Brian](https://en.wikipedia.org/wiki/Monty_Python%27s_Life_of_Brian) to ~cope~ celebrate the release 🍾.

‎docs/code-documentation-guidelines.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Code Documentation Guidelines
2+
3+
In this document you will find the guidelines for adding XML comments to our
4+
codebase. By adding consistent and well-formatted comments to our code, we
5+
benefit on all fronts: the online API docs are a useful reference for people
6+
looking up our APIs, the IntelliSense inside of IDEs will help
7+
developers understand our product better, and contributors and maintainers of
8+
this repository will have all the documentation at hand.
9+
10+
## Guidelines
11+
12+
For comments on our code, we primarily follow the [recommended XML tags documentation][recommended-tags]
13+
by Microsoft. These tags are also best supported by Visual Studio. As a rule
14+
of thumb, complete your code first and just start typing a triple slash
15+
(`///`) above your code. This will suggest all the attributes we expect to
16+
see. The attributes that appear are inferred from your code.
17+
18+
If you're unsure about how to document a certain element, have a look at the
19+
[.NET API docs wiki](https://github.com/dotnet/dotnet-api-docs/wiki) which has
20+
a very extensive description of what kind of comment to add on which element
21+
in the code. We would highly recommend going through that and applying the
22+
same style of comments everywhere.
23+
24+
These are the tags that we would like to see when applicable: `<summary>`,
25+
`<remarks>`, `<returns>`, `<param>`, `<exception>`, `<inheritdoc>`, `<see>`,
26+
`<c>`.
27+
28+
* All public members should have at the very least a `<summary>`
29+
* Keep the descriptions short and concise
30+
* 1-2 lines typically, no screenshots or long code blocks (those belong in
31+
the conceptual docs)
32+
* Make sure the spelling is correct
33+
* Add the descriptions at the highest base class/interface level. On an
34+
implementing type, add `<inheritdoc />` on each member
35+
* If the implemented member differs too much, you can choose to override the
36+
comments; typically this shouldn't be necessary
37+
* When adding `<inheritdoc />` on a class where you want to inherit the
38+
comments from an interface, you will have to be explicit about which
39+
interface to inherit from. Even if the class only implements one
40+
interface. For example: `<inheritdoc cref="IEntry" />` will inherit the
41+
comments from the `IEntry` interface.
42+
* Do **not** add `<inheritdoc />` to overridden members; this will
43+
potentially cause issues in the online API docs system and doesn't add any
44+
value. The documentation is inherited implicitly.
45+
* Where applicable, make references to other types and parameters with the appropriate tags (`<see cref="YourType" />`
46+
and `<paramref name="parameterName" />` respectively). This will create links in IntelliSense and online API docs
47+
* Reference all C# keywords with a `<see langword="keyword" />` tag. For example, for `true`: `<see langword="true" />`
48+
* If you do want to add a minimal amount of code in your comment, use the `<c></c>` tags, which formats it as code
49+
* Think of things you'd like to know as a developer/future-you maintainer:
50+
* Default values that are not obvious
51+
* In which scale a value should be (seconds or milliseconds, 0.0 is nothing, 1.0 is everything)
52+
* What exceptions can you expect, and what triggers them?
53+
54+
If you are looking for examples, browsing through the codebase, searching for
55+
the `<summary>` tag or `///` should give you all kinds of examples.
56+
57+
## References
58+
59+
* [MAUI's code documentation guidelines](https://github.com/dotnet/maui/blob/main/docs/CodeDocumentationGuidelines.md)
60+
* [Style guide](https://github.com/dotnet/dotnet-api-docs/wiki)
61+
* [Recommended XML tags][recommended-tags]
62+
63+
[recommended-tags]: https://learn.microsoft.com/dotnet/csharp/language-reference/xmldoc/recommended-tags

‎docs/update-api-docs.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# How to publish updated API reference documentation
2+
3+
This document describes how to update the reference documentation on https://learn.microsoft.com for the API we publish (for instance, this is the documentation for [UIView](https://learn.microsoft.com/dotnet/api/uikit.uiview)).
4+
5+
API reference documentation should be updated every time we add new APIs, which typically happen when we add support for a new Xcode version.
6+
7+
Since we don't want to go through this process more than once per release, we
8+
don't start until we have the final hash we're going to release (the easiest
9+
is often to wait until packages have been published to NuGet).
10+
11+
The steps are:
12+
13+
1. [Create new monikers](#how_to_create_new_monikers).
14+
This might take a few days, and can be done before we have the final packages.
15+
16+
2. Clone the [binaries](https://apidrop.visualstudio.com/_git/binaries) repository if you haven't already done so.
17+
18+
3. Add our assemblies to the [binaries](https://apidrop.visualstudio.com/_git/binaries) repository.
19+
20+
This can be done automatically with the `update-api-docs.sh` script (can be found next to this document), but for documentation purposes, these are the steps:
21+
22+
* Create new branch off `master`named `netX.Y-xcodeZ.W`.
23+
* Create new directories inside the `dotnet-macios` directory, named according to the monikers created above.
24+
* Copy our platform assemblies and their xml files into their corresponding directory.
25+
* Create a new commit and push it to origin.
26+
27+
4. Go here: [Continuous Integration](https://ops.microsoft.com/#/repos/85f784f4-01e7-ffb8-ed06-a012f7d649c0?tabName=ci) (might need VPN enabled, otherwise sometimes you'll get a 403 error page) and then:
28+
29+
* Expand the '.NET macios API docs' job, and then:
30+
* Change `Target Repo` -> `Target Branch` to `netX.Y-xcodeZ.W` (same branch as created above).
31+
* Change `Source Dll Repo` -> `Repo Branch` to `netX.Y-xcodeZ.W` (yup, same branch again).
32+
* Save.
33+
34+
5. Run this pipeline: [.NET macios API docs](https://apidrop.visualstudio.com/Content%20CI/_build?definitionId=8026). Don't change any options. This will take ~30 minutes.
35+
36+
A new build will show up in OPS a little while after the pipeline has finished running: [Build History](https://ops.microsoft.com#/repos/85f784f4-01e7-ffb8-ed06-a012f7d649c0?tabName=builds) (might need VPN enabled, otherwise sometimes you'll get a 403 error page)
37+
38+
Look for errors/warnings in the build report. If anything needs to be fixed, do that.
39+
40+
Some problems can be fixed in the [dotnet/macios-api-docs](https://github.com/dotnet/macios-api-docs) repository directly, just commit and push them to the `netX.Y-xcodeZ.W` branch. This will automatically create a new build in [Build History](https://ops.microsoft.com#/repos/85f784f4-01e7-ffb8-ed06-a012f7d649c0?tabName=builds).
41+
42+
If any fixes need to be done in [dotnet/macios](https://github.com/dotnet/macios), new packages must be built afterwards, which means starting at the top of this list again.
43+
44+
Please fix all warnings, I went to a great effort to make sure we are free of warnings.
45+
46+
6. The last step is to create a pull request in the [dotnet/macios-api-docs](https://github.com/dotnet/macios-api-docs) repository, from the branch `netX.Y-xcodeZ.W` to `main`.
47+
48+
Once this pull request has been merged, an automated publishing job will get any changes in the `main` branch into the `live` branch, which will then show up on https://learn.microsoft.com.
49+
50+
## How to create new monikers
51+
52+
First read the general information about monikers: [How to define and use monikers](https://learn.microsoft.com/en-us/help/platform/reference-define-use-monikers) (need to be signed in to view)
53+
54+
We need a separate moniker for each platform, so 4 in total.
55+
56+
The format is: "net-<ios|tvos|macos|maccatalyst>-<os version>-<net version>".
57+
58+
So for the initial .NET 10 release, when we shipped APIs for iOS 26.0, tvOS 26.0, macOS 26.0 and Mac Catalyst 26.0, the monikers were:
59+
60+
* net-ios-26.0-10.0
61+
* net-tvos-26.0-10.0
62+
* net-macos-26.0-10.0
63+
* net-maccatalyst-26.0-10.0
64+
65+
We can't create monikers ourselves, we have to request their creation:
66+
67+
1. Go here: [Learn Request Central](https://microsoft.sharepoint.com/teams/Partnerships/SitePages/Learn%20Request%20Central.aspx) (you might have to request access the first time you go here)
68+
a. Under "GitHub Publishing Services" click [Submit your request](https://forms.office.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbRxxUz-ZV53lLrgTaBjGRmtBUNlkzT01CSzNBSE1SRU8yRzU5UTZFNjQyOC4u)
69+
b. Fill in the form with:
70+
1. I am working on publishing a new content set.
71+
2. I need help with updating information architecture (IA) or navigation.
72+
3. Request monikers.
73+
This will lead you to a template to fill an issue. Here's a sample of how I filled it out once: [#480959](https://dev.azure.com/msft-skilling/Content/_workitems/edit/480959).
74+
75+
It can be helpful to view info about all monikers here: [All monikers](https://ops.microsoft.com#/monikers)
76+
77+
## References
78+
79+
* [Document our documentation process/workflow/guidelines - #17401](https://github.com/dotnet/macios/issues/17401)
80+
* [Figure out how to publish XML documentation on our website - #17396](https://github.com/dotnet/macios/issues/17396)
81+
* [Code Documentation Guidelines](code-documentation-guidelines.md)

‎docs/update-api-docs.sh‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
#!/bin/bash -eu
2+
3+
set -o pipefail
4+
IFS=$'\n\t'
5+
6+
# This is a script that builds our platform assemblies, and copies them to the
7+
# repository used to create API reference documentation.
8+
9+
APIDROP_REMOTE=https://apidrop.visualstudio.com/binaries/_git/binaries
10+
APIDROP_REPOSITORY=
11+
BUILD=1
12+
PUSH=
13+
CHECKOUT=
14+
15+
GREEN=$(tput setaf 2 2>/dev/null || true)
16+
YELLOW=$(tput setaf 3 2>/dev/null || true)
17+
MAGENTA=$(tput setaf 5 2>/dev/null || true)
18+
BLUE=$(tput setaf 6 2>/dev/null || true)
19+
RED=$(tput setaf 9 2>/dev/null || true)
20+
CLEAR=$(tput sgr0 2>/dev/null || true)
21+
22+
BACKGROUND_COLOR=$GREEN
23+
BRANCH_COLOR=$BLUE
24+
LINK_COLOR=$MAGENTA
25+
PATH_COLOR=$BLUE
26+
NOTICE_COLOR=$YELLOW
27+
REMOTE_COLOR=$MAGENTA
28+
PLATFORM_COLOR=$BLUE
29+
30+
while ! test -z "${1:-}"; do
31+
case $1 in
32+
--help | -\? | -h)
33+
echo "$(basename "$0"):"
34+
echo " Builds the current checkout, and copies the product assemblies to apidrop.visualstudio.com's binaries repository to update the API docs."
35+
echo ""
36+
echo " Options:"
37+
echo " -h --help Show this help"
38+
echo " -v --verbose Make verbose"
39+
echo " -a --apidrop-repository= Specify the local path to the binaries repository ($REMOTE_COLOR$APIDROP_REMOTE$CLEAR)."
40+
echo " -p --push If specified, push the commit with the updated assemblies to the binaries repository (otherwise this will have to be done manually)."
41+
echo " -s --skip-build If specified, any existing build will be used instead of rebuilding the checkout."
42+
echo " -c --checkout= The path to the dotnet/macios checkout to use."
43+
exit 0
44+
;;
45+
-v | --verbose)
46+
set -x
47+
shift
48+
;;
49+
-a=* | --apidrop-repository=*)
50+
APIDROP_REPOSITORY="${1//*=/}"
51+
shift
52+
;;
53+
-a | --apidrop-repository)
54+
APIDROP_REPOSITORY="${2:-}"
55+
shift 2
56+
;;
57+
-p | --push)
58+
PUSH=1
59+
shift
60+
;;
61+
-c | --checkout)
62+
CHECKOUT="${2:-}"
63+
shift 2
64+
;;
65+
-c=* | --checkout=*)
66+
CHECKOUT="${1//*=/}"
67+
shift
68+
;;
69+
-s | --skip-build)
70+
BUILD=
71+
shift
72+
;;
73+
*)
74+
echo "${RED}$(basename "$0"): Unknown option: $MAGENTA$1$RED. Pass --help to view the available options.${CLEAR}"
75+
exit 1
76+
;;
77+
esac
78+
done
79+
80+
echo "${BACKGROUND_COLOR}$(basename "$0"): Build the current macios checkout and copy the product assemblies to the apidrop.visualstudio.com's binaries repository to update the API docs... Pass --help for help."
81+
82+
if test -n "${CHECKOUT:-}"; then
83+
cd "$CHECKOUT"
84+
fi
85+
86+
cd "$(git rev-parse --show-toplevel)"
87+
MACIOS_PATH=$(pwd)
88+
89+
if [ -n "$(git status --porcelain --ignore-submodule)" ]; then
90+
echo "${RED}Working directory is not clean:${CLEAR}"
91+
git status --ignore-submodule | sed 's/^/ /'
92+
exit 1
93+
fi
94+
95+
if test -z "$APIDROP_REPOSITORY"; then
96+
echo "${NOTICE_COLOR}The path to the apidrop repository was not found, so looking for it...${CLEAR}"
97+
while [[ "$(pwd)" != "/" ]]; do
98+
cd ..
99+
if test -d apidrop.visualstudio.com/binaries; then
100+
cd apidrop.visualstudio.com/binaries
101+
if REMOTE=$(git remote get-url origin); then
102+
if [[ "$REMOTE" == "$APIDROP_REMOTE" ]]; then
103+
APIDROP_REPOSITORY=$(pwd)
104+
echo "${BACKGROUND_COLOR} Located the apidrop repository: ${PATH_COLOR}$APIDROP_REPOSITORY${CLEAR}"
105+
break
106+
fi
107+
echo "${NOTICE_COLOR} Discarded the git checkout in ${PATH_COLOR}$(pwd)${NOTICE_COLOR}, because its remote $REMOTE_COLOR$REMOTE$NOTICE_COLOR does not match the expected remote $REMOTE_COLOR$APIDROP_REMOTE$NOTICE_COLOR.${CLEAR}"
108+
else
109+
echo "${NOTICE_COLOR} Discarded the directory ${PATH_COLOR}$(pwd)${NOTICE_COLOR}, because it's not a git checkout.${CLEAR}"
110+
fi
111+
cd ../..
112+
fi
113+
done
114+
if test -z "$APIDROP_REPOSITORY"; then
115+
echo "${RED}Could not find a local checkout of the $REMOTE_COLOR$APIDROP_REMOTE$RED repository. Check it out, and then pass the path using ${BACKGROUND_COLOR}--apidrop-repository=/path/to/checkout${RED}.${CLEAR}"
116+
exit 1
117+
fi
118+
else
119+
echo "${BACKGROUND_COLOR}Using the directory $PATH_COLOR$APIDROP_REPOSITORY$BACKGROUND_COLOR as the checkout for the $REMOTE_COLOR$APIDROP_REMOTE$BACKGROUND_COLOR repository.${CLEAR}"
120+
fi
121+
122+
cd "$MACIOS_PATH"
123+
124+
if test -n "$BUILD"; then
125+
echo "${BACKGROUND_COLOR}Building macios (pass --skip-build to skip)...${CLEAR}"
126+
(
127+
make reset
128+
make git-clean-all
129+
git clean -xfd
130+
./configure
131+
make all -j8
132+
make install -j8
133+
) 2>&1 | sed 's/^/ /'
134+
else
135+
echo "${BACKGROUND_COLOR}Skipped building macios...${CLEAR}"
136+
fi
137+
138+
TMPFILE=$(mktemp)
139+
make -C "$MACIOS_PATH"/tools/devops print-variable-value-to-file "FILE=$TMPFILE" VARIABLE=XCODE_VERSION
140+
XCODE_VERSION=$(cat "$TMPFILE")
141+
make -C "$MACIOS_PATH"/tools/devops print-variable-value-to-file "FILE=$TMPFILE" VARIABLE=DOTNET_TFM
142+
DOTNET_TFM=$(cat "$TMPFILE")
143+
make -C "$MACIOS_PATH"/tools/devops print-variable-value-to-file "FILE=$TMPFILE" VARIABLE=DOTNET_PLATFORMS
144+
DOTNET_PLATFORMS=$(cat "$TMPFILE")
145+
rm -f "$TMPFILE"
146+
147+
BINARIES_BRANCH=$DOTNET_TFM-xcode$XCODE_VERSION
148+
149+
echo "${BACKGROUND_COLOR}Copying assemblies to the branch ${BRANCH_COLOR}${BINARIES_BRANCH}${BACKGROUND_COLOR} in the binaries repository (${PATH_COLOR}${APIDROP_REPOSITORY}${BACKGROUND_COLOR})...${CLEAR}"
150+
cd "$APIDROP_REPOSITORY"
151+
git checkout master
152+
git pull
153+
if ! git checkout -b "$BINARIES_BRANCH"; then
154+
echo "${RED}Failed to checkout the branch $BRANCH_COLOR$BINARIES_BRANCH$RED in $PATH_COLOR$APIDROP_REPOSITORY$RED - if the branch already exists, please delete it first.$CLEAR"
155+
exit 1
156+
fi
157+
mkdir -p "$APIDROP_REPOSITORY/dotnet-macios/"
158+
159+
cd "$MACIOS_PATH"
160+
161+
NETVERSION=${DOTNET_TFM//net/}
162+
COMMIT_MESSAGE="Add updated assemblies for .NET $NETVERSION:"
163+
IFS=' '; for platform in $DOTNET_PLATFORMS; do
164+
PLATFORM_UPPERCASE=$(echo "$platform" | tr '[:lower:]' '[:upper:]')
165+
PLATFORM_LOWERCASE=$(echo "$platform" | tr '[:upper:]' '[:lower:]')
166+
167+
OSVERSION=$(grep "^${PLATFORM_UPPERCASE}_NUGET_OS_VERSION=" Make.versions | sed 's/.*=//')
168+
COMMIT_MESSAGE="$COMMIT_MESSAGE $platform $OSVERSION,"
169+
170+
DIR=$APIDROP_REPOSITORY/dotnet-macios/net-$PLATFORM_LOWERCASE-$OSVERSION-$NETVERSION
171+
mkdir -p "$DIR"
172+
cp "_build/Microsoft.$platform.Ref.net${NETVERSION}_$OSVERSION/ref/net$NETVERSION/Microsoft.$platform.dll" "$DIR/"
173+
cp "_build/Microsoft.$platform.Ref.net${NETVERSION}_$OSVERSION/ref/net$NETVERSION/Microsoft.$platform.xml" "$DIR/"
174+
echo "${BACKGROUND_COLOR} Copied $PLATFORM_COLOR$platform$BACKGROUND_COLOR assemblies to $PATH_COLOR$DIR$CLEAR"
175+
done
176+
177+
# remove the last character (",")
178+
COMMIT_MESSAGE="${COMMIT_MESSAGE/%?}"
179+
180+
echo "${BACKGROUND_COLOR}Creating the commit in the binaries repository (${PATH_COLOR}${APIDROP_REPOSITORY}${BACKGROUND_COLOR})...${CLEAR}"
181+
cd "$APIDROP_REPOSITORY/dotnet-macios/"
182+
git add .
183+
git commit -m "$COMMIT_MESSAGE"
184+
185+
if test -n "$PUSH"; then
186+
git push
187+
echo "${BACKGROUND_COLOR}Pushed a commit with the updated assemblies to the ${BRANCH_COLOR}$BINARIES_BRANCH${BACKGROUND_COLOR} branch in ${PATH_COLOR}${APIDROP_REPOSITORY}${BACKGROUND_COLOR}.${CLEAR}"
188+
echo "${BACKGROUND_COLOR}A commit has been created and pushed in ${PATH_COLOR}${APIDROP_REPOSITORY}${BACKGROUND_COLOR}.${CLEAR}"
189+
else
190+
echo "${BACKGROUND_COLOR}A commit that is ready to be pushed has been created in ${PATH_COLOR}${APIDROP_REPOSITORY}${BACKGROUND_COLOR}.${CLEAR}"
191+
fi
192+
193+
echo "${BACKGROUND_COLOR}Please read the instructions (${LINK_COLOR}update-api-docs.md${BACKGROUND_COLOR}) for the next steps.${CLEAR}"

0 commit comments

Comments
 (0)