How to document a struct within a struct in XCode (Swift or Obj-C)

Question

We all know that when documenting a struct, you can use @struct for your struct and use @field to explains the content within the struct.

But how to document a struct with some fields that is within another struct?

In Swift, the example code will be:

struct Constants{
    static let kButtonHeight : CGFloat = 0
    struct Color {
      static let kCloud: UIColor = UIColor(red: 236/255, green: 240/255, blue: 241/255, alpha: 1.0)
    }
}

Thank you so much!

Answer 1

If you're doing this in Swift, you can prefix anything (type, property, or instance, etc.) with either single-line comments marked by /// or multi-line comments beginning with /** . So your documentation could simply be:

/// A global container for all constants
struct Constants{
    /// The default button height
    static let kButtonHeight : CGFloat = 0

    /// Constant UIColor instances for my app
    struct Color {
        /// The cloud color - a very pale blue-white
        static let kCloud: UIColor = UIColor(red: 236/255, green: 240/255, blue: 241/255, alpha: 1.0)
    }
}

The documentation attaches immediately -- option click on a name and you get the relevant documentation:

Answer 2

I would define the Color struct outside (and before/above) the definition of Constants, and then the definition of constants would have a member of type Color, but without the 'nested' definitions. If you consider CGRect, this is a 'struct of structs' (a CGPoint and a CGSize) but those member structs are perfectly usable on their own as well..