Images / diagrams in documentation comments?

Does anyone use this and get it to display in Xcode? I can't get it working. I'm talking about code in normal swift files, not playgrounds.

I'd love to be able to put diagrams in code comments, and view them without having to open up other programs.

Example:

/// ![test_diagram](/Users/me/fullpathto/test-image.png)
/// ![test_image](http://devimages.apple.com.edgekey.net/assets/elements/icons/128x128/xcode.png)

Neither one displays anything in the documentation popover or the Quick Help Inspector.

The docs act like it works: https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/Images.html#//apple_ref/doc/uid/TP40016497-CH17-SW1

Rob

2 Likes

Instead of using the three leading slashes, have you tried the /** ... */ construct, that's used in the documentation?

/**
    ![test_diagram](/Users/me/fullpathto/test-image.png)
*/

That may be a departure point for the two methods of defining Quick Help comments.

That doesn't work for me either. I usually avoid that comment style because it's hard to see what it's using as your indentation level.

The comment type (/// vs. //* */) wouldn’t matter.

It is supposed to be supported according to this:
https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/MarkupFunctionality.html#//apple_ref/doc/uid/TP40016497-CH54-SW1

I can’t get it to work either. It is probably a bug. It may be a NSURLRequest sandboxing bug where it tries to work but is blocked. It is not in common use, so likely it broke and nobody noticed. You could file a bug with Apple.

This is a known issue (rdar://39360782). I narrowly missed the window of opportunity to update the markup reference before it became part of the archived documentation.