Comments (18)
@theMomax Fantastic! I was just thinking about this again recently, perfect timing :) Thanks for the huge effort on this, I'm very excited to start using it!
from swift-docc.
Comment by Robert Nikander (JIRA)
@Kyle-Ye, no, it's definitely not a "feature"! Swift encourages extensions of types from other modules. Look at SwiftUI - the entire library of "view modifiers" are extensions. Other examples would be an algorithms package that extends the standard collection protocols, or a math package like my example. We need to be able to document code like that.
from swift-docc.
@LeoNatan this issue only discusses Swift extensions and the solution I'm developing right now also only applies to Swift (although the same approach should also be applicable to Objective C categories). Feel free to open a separate issue for ObjC category support if you have demand for it!
from swift-docc.
@adamwulf The Swift compiler flags are merged, so it is technically possible to document extensions with DocC now, but I'm still working on getting the flags into higher-level commands in the Swift Package Manager and the DocC Package Plugin.
There also have been some problems with the recent Trunk Development toolchain builds, so it's a little tricky to get it working with the public toolchain builds.
Please be patient one more week. I'll post on the forums once everything is ready.
In the meantime, here is the simplest setup (macOS only, unfortunately):
- Xcode Version 14.1 (14B47b)
- Toolchain Swift Development Snapshot 2022-11-03 on macOS Ventura Version 13.0.1 (22A400)
- Add this to your
Package.swift
file:swiftSettings: [.unsafeFlags(["-emit-extension-block-symbols"])]
- build in Xcode (via
Product > Build Documentation
orxcodebuild docbuild
)
Note that it might also work with more recent toolchain builds, but that is the last version I tried it with that way.
from swift-docc.
@theMomax Wonderful thanks! Take all the time you need, especially as we approach the holidays 😄 Thanks!
from swift-docc.
I can't reproduce what you describe. rnikander (JIRA User)
I'm trying to reproduce with the SlothCreator demo https://developer.apple.com/documentation/xcode/slothcreator_building_docc_documentation_in_xcode
First I add an extension to Sloth
extension Sloth {
/// Format the matrix with a default style
public func formatted() -> String {
return ""
}
}
And then I can see it like this
And I can also reference it like this
On Sloth, it is ``formatted()``. On other part of DocC, it is ``Sloth/formatted()``
from swift-docc.
Comment by Robert Nikander (JIRA)
Sorry, I should have been more specific in my bug report. This is about extending types from other packages. That may not be important for the Sloth
package, but you can imagine something like the linear algebra package in my example, that extends the simd matrix types. Try extending a system type, or specifically the simd_float3x3
that I used in my example.
from swift-docc.
Yes, I can reproduce this by adding a extension to Int
extension Int {
/// This is a test function
public func aa(){
return
}
}
But I kindly think it is more of a feature than a bug.
Since the Int or simd_float3x3 is not a structure we define(or in our package). We are not authorised to document this function. Even the function was declared as public.
But yes, we could implement this as long as the code owner of the repo agree on this feature proposal.
from swift-docc.
(Discussion about this topic started in https://forums.swift.org/t/docc-and-extensions/53132)
from swift-docc.
I think https://forums.swift.org/t/docc-and-extensions/53132/4 makes sense to me. We can add the feature / fix the "bug" without significant changes to DocC. The problem is to decide from a UX perspective of how to link to those symbols and render them in the documentation.
I'm glad to hear your suggestion in the forum's discussion on this. rnikander (JIRA User)
from swift-docc.
The feature's not quite fixed yet; one of its constituent PRs just was.
from swift-docc.
Once again, there are more PRs to merge before this feature is 100% resolved.
from swift-docc.
Would Objective C categories be documented when this issue is solved, or is that a completely different set of requirements/bug?
from swift-docc.
Thank you!
from swift-docc.
As per the last Documentation WG discussion, here is a list of completed and remaining work items related to this issue. All PRs and issues are listed in the order in which they should be addressed/merged.
Feature Development
Feature development is basically complete, only one last very small PR needs to be reviewed and merged.
- swiftlang/swift#59047
- apple/swift-docc-symbolkit#39
- apple/swift-docc-symbolkit#45
- apple/swift-docc-symbolkit#48
- #369
- swiftlang/swift#61406
Feature Enablement
Feature enablement is just about adding the command line flags to all the relevant repositories: swift integrated driver, swift-driver, swift-package-manager, and finally swift-docc-plugin.
- swiftlang/swift#61637
- apple/swift-driver#1205
- swiftlang/swift-package-manager#5978 (Swift 5.8 backport: swiftlang/swift-package-manager#5985)
- apple/swift-docc-plugin#34
Bugs/Bugfixes
There are two bugs currently known:
from swift-docc.
Once again, not quite there yet. See @theMomax's last comment for the current status.
from swift-docc.
Is this issue finally closed - I see a few items still unchecked in the todo list above. I'm trying to build and run locally to take advantage of this new feature, but I don't see how to enable it. It appears the flags are still not merged in, is that right?
from swift-docc.
The enablement discussion for my implementation has started! Check out the thread here for details on how to use the feature and updates on its enablement in the Swift 5.8 release toolchain.
cc @adamwulf
from swift-docc.
Related Issues (20)
- source link line number mismatch HOT 2
- Support svg images in Xcode inline documentation HOT 2
- Pass "link summaries" instead of "resolved information" in external documentation source responses
- Can't document - -= / /= operators HOT 8
- DocC generates inconsistent output for global Objective-C functions that are renamed to be associated with a type in Swift HOT 2
- Error when publishing to GitHub Pages HOT 6
- Linkable glossary
- Document Objective-C extensions with DocC HOT 2
- Xcode "Build documentation" not working with Swift Macro package in project HOT 5
- Curating a module under a technology root causes the sidebar to not show Objective-C symbols
- illegal hardware instruction HOT 4
- This mangled quote/code fence results in a crash HOT 1
- `@DeprecationSummary` directive doesn't always have an effect HOT 2
- Xcode does not provide fix for operator functions HOT 4
- Make DocC-Generated Website Indexable by Search Engines HOT 2
- Slices of Snippets don't have indentation removed HOT 1
- optional force unwrap fails if target name contains special characters
- Snippet slicing does not handle multiline string literals correctly
- Migrate to Swift 6
- Deprecated Objective-C methods not being marked as Deprecated
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from swift-docc.