D 2021-04-08T02:16:07.996 L API\sReview\sfor\s1.0 N text/x-markdown P e8d9e5493326520b4bc8fd38013cad021e1264faae0a587faedcc4f59b63cbd3 U js W 10288 # API Review for 1.0 For the 1.0 release, all APIs should be reviewed, as starting 1.0, they are supposed to be stable. Right now, we have fhe following: ## Protocols * ✅ OFApplicationDelegate * ✅ OFCollection * ✅ OFComparing * ✅ OFCopying * ✅ OFCryptographicHash * ❌ OFDatagramSocketDelegate * ❌ OFDNSResolverHostDelegate * ❌ OFDNSResolverQueryDelegate * ✅ OFEnumeration * ✅ OFFastEnumeration * API given by the compiler * ❌ OFHTTPClientDelegate * ❌ OFHTTPServerDelegate * ✅ OFIPSocketAsyncConnecting * Private * ❌ OFIPXSocketDelegate * ❌ OFJSONRepresentation * ❌ OFKernelEventObserverDelegate * ❌ OFKeyValueCoding * ✅ OFLocking * ❌ OFMessagePackRepresentation * ✅ OFMutableCopying * ❌ OFObject * ❌ OFReadyForReadingObserving * ❌ OFReadyForWritingObserving * ❌ OFSequencedPacketSocketDelegate * ❌ OFSerialization * ❌ OFSPXSocketDelegate * ❌ OFSPXStreamSocketDelegate * ❌ OFStreamDelegate * ❌ OFStreamSocketDelegate * ❌ OFStringXMLUnescapingDelegate * ❌ OFTCPSocketDelegate * ❌ OFTLSSocket * ❌ OFTLSSocketDelegate * ❌ OFUDPSocketDelegate * ❌ OFXMLElementBuilderDelegate * ❌ OFXMLParserDelegate ## Classes * ✅ NSString * Fake class has no API and is only used to make string boxing via `@(cString)` work. * ❌ OFAAAADNSResourceRecord * ❌ OFAcceptFailedException * ✅ OFAdjacentArray * Private * ✅ OFAdjacentSubarray * Private * ❌ OFADNSResourceRecord * ❌ OFAllocFailedException * ❌ OFAlreadyConnectedException * ❌ OFApplication * Needs a better method (name) to get argc/argv * ❌ OFArray * ❌ OFBindFailedException * ✅ OFBitSetCharacterSet * Private * ✅ OFBlock * Has no API * ✅ OFBytesValue * Private * ❌ OFChangeCurrentDirectoryPathFailedException * ❌ OFCharacterSet * ❌ OFCharacterSet (URLCharacterSets) * ❌ OFChecksumMismatchException * ❌ OFCNAMEDNSResourceRecord * ❌ OFColor * ❌ OFCondition * ❌ OFConditionBroadcastFailedException * ❌ OFConditionSignalFailedException * ❌ OFConditionStillWaitingException * ❌ OFConditionWaitFailedException * ❌ OFConnectionFailedException * ❌ OFConstantString * ❌ OFCopyItemFailedException * ✅ OFCountedMapTableSet * Private * ❌ OFCountedSet * ❌ OFCreateDirectoryFailedException * ❌ OFCreateSymbolicLinkFailedException * ❌ OFCreateWindowsRegistryKeyFailedException * ❌ OFData * ✅ OFData (CryptographicHashing) * ❌ OFDatagramSocket * ❌ OFData (MessagePackParsing) * ❌ OFDate * ❌ OFDeleteWindowsRegistryKeyFailedException * ❌ OFDeleteWindowsRegistryValueFailedException * ❌ OFDictionary * ❌ OFDictionary (FileAttributes) * ✅ OFDimensionValue * Private * ❌ OFDNSQuery * ❌ OFDNSQueryFailedException * ❌ OFDNSResolver * ✅ OFDNSResolverSettings * Private * ❌ OFDNSResourceRecord * ❌ OFDNSResponse * ❌ OFEnumerationMutationException * ❌ OFEnumerator * ✅ OFEpollKernelEventObserver * Private * ❌ OFException * ❌ OFFile * ❌ OFFileManager * ✅ OFFileURLHandler * Private * ❌ OFGetCurrentDirectoryPathFailedException * ❌ OFGetOptionFailedException * ❌ OFGetWindowsRegistryValueFailedException * ✅ OFGlobalBlock * Doesn't have an API * ❌ OFGZIPStream * ❌ OFHashAlreadyCalculatedException * ❌ OFHINFODNSResourceRecord * ❌ OFHMAC * ✅ OFHostAddressResolver * Private * ❌ OFHTTPClient * ❌ OFHTTPCookie * ❌ OFHTTPCookieManager * ❌ OFHTTPRequest * ❌ OFHTTPRequestFailedException * ❌ OFHTTPResponse * ❌ OFHTTPServer * ✅ OFHTTPURLHandler * Private * ❌ OFInflate64Stream * ❌ OFInflateStream * ❌ OFINICategory * ❌ OFINIFile * ✅ OFINIFileSettings * Private * ❌ OFInitializationFailedException * ❌ OFInvalidArgumentException * ❌ OFInvalidEncodingException * ❌ OFInvalidFormatException * ❌ OFInvalidJSONException * ❌ OFInvalidServerReplyException * ✅ OFInvertedCharacterSet * Private * ❌ OFInvocation * ✅ OFIPSocketAsyncConnector * Private * ❌ OFIPXSocket * ❌ OFKernelEventObserver * ✅ OFKqueueKernelEventObserver * Private * ❌ OFLHAArchive * ❌ OFLHAArchiveEntry * ✅ OFLHADecompressingStream * Private * ❌ OFLinkFailedException * ❌ OFList * ❌ OFListenFailedException * ❌ OFLoadPluginFailedException * ❌ OFLocale * ❌ OFLockFailedException * ❌ OFMalformedXMLException * ✅ OFMallocBlock * Doesn't have an API * ❌ OFMapTable * ✅ OFMapTableDictionary * Private * ❌ OFMapTableEnumerator * ✅ OFMapTableSet * Private * ✅ OFMD5Hash * Only overrides methods from superclass * ❌ OFMemoryNotPartOfObjectException * ❌ OFMessagePackExtension * ❌ OFMethodSignature * ❌ OFMoveItemFailedException * ✅ OFMutableAdjacentArray * Private * ❌ OFMutableArray * ❌ OFMutableData * ❌ OFMutableDictionary * ❌ OFMutableLHAArchiveEntry * ✅ OFMutableMapTableDictionary * Private * ✅ OFMutableMapTableSet * Private * ❌ OFMutablePair * ❌ OFMutableSet * ❌ OFMutableString * ❌ OFMutableTarArchiveEntry * ❌ OFMutableTriple * ❌ OFMutableURL * ✅ OFMutableUTF8String * Private * ❌ OFMutableZIPArchiveEntry * ✅ OFMutex * ❌ OFMXDNSResourceRecord * ✅ OFNonretainedObjectValue * Private * ❌ OFNotImplementedException * ❌ OFNotOpenException * ❌ OFNSDNSResourceRecord * ✅ OFNull * ❌ OFNumber * ❌ OFObject (KeyValueCoding) <OFKeyValueCoding> * ❌ OFObject <OFObject> * ❌ OFObject (OFSerialization) * ❌ OFObserveFailedException * ❌ OFOpenItemFailedException * ❌ OFOpenWindowsRegistryKeyFailedException * ❌ OFOptionsParser * ❌ OFOutOfMemoryException * ❌ OFOutOfRangeException * ❌ OFPair * Should be an `OFCollection` * Should conform to `OFComparing` * ❌ OFPlugin * ✅ OFPointerValue * Private * ✅ OFPointValue * Private * ✅ OFPollKernelEventObserver * Private * ❌ OFPTRDNSResourceRecord * ✅ OFRangeCharacterSet * Private * ✅ OFRangeValue * Private * ❌ OFReadFailedException * ❌ OFReadOrWriteFailedException * ✅ OFRectangleValue * Private * ✅ OFRecursiveMutex * ❌ OFRemoveItemFailedException * ❌ OFResolveHostFailedException * ❌ OFRetrieveItemAttributesFailedException * ✅ OFRIPEMD160Hash * Only overrides methods from superclass * ❌ OFRPDNSResourceRecord * ❌ OFRunLoop * ✅ OFSandbox * Private in 1.0 (but public in trunk) * ✅ OFSandboxActivationFailedException * Private in 1.0 (but public in trunk) * ❌ OFSecureData * ❌ OFSeekableStream * ❌ OFSeekFailedException * ✅ OFSelectKernelEventObserver * Private * ❌ OFSequencedPacketSocket * ❌ OFSet * ❌ OFSetItemAttributesFailedException * ❌ OFSetOptionFailedException * ❌ OFSettings * ❌ OFSetWindowsRegistryValueFailedException * ✅ OFSHA1Hash * Only overrides methods from superclass * ✅ OFSHA224Hash * Only overrides methods from superclass * ✅ OFSHA224Or256Hash * Has no API - only public because its subclasses are public * ✅ OFSHA256Hash * Only overrides methods from superclass * ✅ OFSHA384Hash * Only overrides methods from superclass * ✅ OFSHA384Or512Hash * Has no API - only public because its subclasses are public * ✅ OFSHA512Hash * Only overrides methods from superclass * ❌ OFSOADNSResourceRecord * ❌ OFSortedList * ❌ OFSPXSocket * ❌ OFSPXStreamSocket * ❌ OFSRVDNSResourceRecord * ✅ OFStackBlock * Doesn't have an API * ❌ OFStdIOStream * ❌ OFStillLockedException * ❌ OFStream * ❌ OFStreamSocket * ❌ OFString * ✅ OFString (CryptographicHashing) * ❌ OFString (JSONParsing) * ❌ OFString (PathAdditions) * ❌ OFString (PropertyListParsing) * ❌ OFString (Serialization) * ❌ OFString (URLEncoding) * ❌ OFString (XMLEscaping) * ❌ OFString (XMLUnescaping) * ✅ OFSubarray * Private * ❌ OFSubprocess * ❌ OFSystemInfo * ❌ OFTarArchive * ❌ OFTarArchiveEntry * ❌ OFTCPSocket * ✅ OFTCPSocketSOCKS5Connector * Private * ❌ OFThread * ❌ OFThreadJoinFailedException * ✅ OFThreadPool * ❌ OFThreadStartFailedException * ❌ OFThreadStillRunningException * ❌ OFTimer * ❌ OFTriple * Should be an `OFCollection` * Should conform to `OFComparing` * ❌ OFTruncatedDataException * ❌ OFTXTDNSResourceRecord * ❌ OFUDPSocket * ❌ OFUnboundNamespaceException * ❌ OFUnboundPrefixException * ❌ OFUndefinedKeyException * ❌ OFUnknownXMLEntityException * ❌ OFUnlockFailedException * ❌ OFUnsupportedProtocolException * ❌ OFUnsupportedVersionException * ❌ OFURL * ❌ OFURLHandler * ✅ OFUTF8String * Private * ❌ OFValue * ✅ OFWin32ConsoleStdIOStream * Private * ❌ OFWindowsRegistryKey * ❌ OFWriteFailedException * ❌ OFXMLAttribute * Needs rename: `namespace` to `namespaceURI` to avoid problems in C++ * ✅ OFXMLCDATA * ✅ OFXMLCharacters * ❌ OFXMLComment * Needs a property to access the comment - `-[stringValue]` is just `@""` * ❌ OFXMLElement * Needs rename: `namespace` to `namespaceURI` to avoid problems in C++ * ❌ OFXMLElementBuilder * Needs rename: `namespace` to `namespaceURI` to avoid problems in C++ * ❌ OFXMLElement (OFSerialization) * ❌ OFXMLNode * Should `-[XMLStringWithIndentation:level:]` be private? * ❌ OFXMLParser * Needs rename: `namespace` to `namespaceURI` to avoid problems in C++ * ❌ OFXMLProcessingInstructions * Needs a property to access the PI - `-[stringValue]` is just `@""` * ❌ OFZIPArchive * ❌ OFZIPArchiveEntry ## Commands **Get all protocols** ```sh find src -name '*.h' -and -not -name '*+Private.h' -and -not -wholename 'src/bridge/*' -and -not -wholename 'src/runtime/*' -exec grep '^@protocol ' {} \; | grep -v '^@protocol.*;' | sed 's/^@protocol /* ❌ /' | sed 's/:.*//' | sed 's/<.*>//' | sort ``` **Get all classes** ```sh find src -name '*.h' -and -not -name '*+Private.h' -and -not -wholename 'src/bridge/*' -and -not -wholename 'src/runtime/*' -exec grep '^@interface ' {} \; | sed 's/^@interface /* ❌ /' | sed 's/:.*//' | sed 's/OF_GENERIC(.*)//' | sed 's//\>/' | sort ``` Z ad7d366d4a62c9b801e44e4d7d4da875