Skip to content

Commit

Permalink
Update Documentation Guide (#28)
Browse files Browse the repository at this point in the history
# Update Documentation Guide

## ⚙️ Release Notes 
- Updates the documentation guide.


## 📝 Code of Conduct & Contributing Guidelines 

By submitting creating this pull request, you agree to follow our [Code
of
Conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md)
and [Contributing
Guidelines](https://github.com/StanfordSpezi/.github/blob/main/CONTRIBUTING.md):
- [x] I agree to follow the [Code of
Conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md)
and [Contributing
Guidelines](https://github.com/StanfordSpezi/.github/blob/main/CONTRIBUTING.md).
  • Loading branch information
PSchmiedmayer authored Aug 24, 2023
1 parent 6699ff8 commit 7a8df79
Showing 1 changed file with 9 additions and 1 deletion.
10 changes: 9 additions & 1 deletion DOCUMENTATIONGUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,12 @@ The documentation MUST use appropriate [GitHub markdown syntax](https://docs.git
Related types within the module MUST be linked using [markdown links](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links) or [DocC links](https://www.swift.org/documentation/docc/formatting-your-documentation-content#Link-to-Symbols-and-Other-Content).
Essential external types SHOULD be linked to, e.g., the Apple Documentation like the [`@State`](https://developer.apple.com/documentation/swiftui/state) property wrapper.

Code examples MUST use the proper syntax highlighting.
Code examples MUST use proper syntax highlighting, e.g.,:
````md
```swift
let name = "Paul"
```
````

Elements like [notes and other asides](https://www.swift.org/documentation/docc/documenting-a-swift-framework-or-package) SHOULD be used.
GitHub offers equal elements for README documents, e.g.:
Expand All @@ -41,6 +46,9 @@ GitHub offers equal elements for README documents, e.g.:
> An important element ...
```

You SHOULD use [`@_documentation(visibility: ...)`](https://github.com/apple/swift/blob/main/docs/ReferenceGuides/UnderscoredAttributes.md#_documentationvisibility-) to hide elements from the documentation that should not appear in the public documentation.
It is RECOMMENDED to use `@_documentation(visibility: internal)` to an `@_exported import` statement to ensure that all public symbols of the imported module are not exposed in the documentation of the Spezi module.

You can learn more about DocC by reading the documentation or watching the DocC Apple World Wide Developer Conference (WWDC) videos:
- [swift.org - DocC Documentation](https://www.swift.org/documentation/docc/#)
- [WWDC 2023 - Create rich documentation with Swift-DocC](https://developer.apple.com/wwdc23/10244)
Expand Down

0 comments on commit 7a8df79

Please sign in to comment.