Code blocks do not work with star-prefixed comments #344

Open
ircubic opened this Issue Apr 2, 2013 · 6 comments

Comments

Projects
None yet
5 participants

ircubic commented Apr 2, 2013

I was trying to include a code block in our appledoc comments, which we usually write with stars down the left side. This did not work, and the code block text was treated as a regular paragraph, so it seems that appledoc does not recognize code blocks when stars are used. Code blocks work fine when all the stars are removed, though.

Owner

tomaz commented Apr 2, 2013

This was working when I tested it last time (a long time ago :). Just for sanity check: do you prefix code block lines with tab or 4 spaces after the star? You should also have an empty line as delimiter between any previous "paragraph".

ircubic commented Apr 2, 2013

Yes, I had 5 spaces (one space buffer like all comment text, then 4 spaces for the code indent) before all of the code (more, obviously, for further indented code), and I left empty lines above and below. I can run more minimal tests when I get home to see if it wasn't just a fluke, as I only have one code block in all of my comments so far and it's kind of a big one.

Owner

tomaz commented Apr 2, 2013

Ok, then it must be regression...

Same here. appledoc version: 2.2 (build 961) installed with homebrew.

This works fine:

/** Foo

 Example:

     [UIString stringWithFormat:"%d", 42];

 */

This doesn't:

/** Foo
 *
 * Example:
 *
 *     [UIString stringWithFormat:"%d", 42];
 *
 */

flegallo commented May 3, 2014

👍

Contributor

idpaterson commented May 3, 2014

This problem has indeed been around for a long time. In addition to * prefixes I also avoid non-prefixed comments because Xcode has never maintained that spacing on copy/paste or Re-Indent. I use uncrustify followed by Re-Indent for code formatting so this has always been a dealbreaker for star comments. So instead, I always use the /// triple slash syntax because it works consistently.

I discussed these problems in length with examples in my pull request to add /// comments to VVDocumenter: onevcat/VVDocumenter-Xcode#18. Since it sounds like others are still having trouble with this, here is the relevant excerpt:

Why /// instead of stars or whitespace?

If anyone is wondering why I use ///, the reason is fairly simple, it's more reliable in Appledoc. Consider the following documentation that contains example code. In Appledoc, example code is simply indented 4 or more spaces.

/// This method does something very useful.
///
/// The following example shows an appropriate use of `doSomething`
///
///    NSLog(@"%@", thing.someProperty);  // Logs "A"
///    [thing doSomething];
///    NSLog(@"%@", thing.someProperty);  // Logs "B"
- (void)doSomething;

This generates the following in Appledoc, looks pretty good.

Documentation example with 3 slashes


However, if we try the same code with star-prefixed comments the result is much different. This is probably a bug in Appledoc, but it has been around for a long time. Examples are simply not picked up when a star prefix is used.

/**
 * This method does something very useful.
 *
 * The following example shows an appropriate use of `doSomething`
 * 
 *     NSLog(@"%@", thing.someProperty);  // Logs "A"
 *     [thing doSomething];
 *     NSLog(@"%@", thing.someProperty);  // Logs "B"
 */
- (void)doSomething;

Documentation example with star prefix


It may seem to work fine without the star prefix.

/**
  This method does something very useful.

  The following example shows an appropriate use of `doSomething`

      NSLog(@"%@", thing.someProperty);  // Logs "A"
      [thing doSomething];
      NSLog(@"%@", thing.someProperty);  // Logs "B"
 */

Documentation with whitespace prefix


However, Appledoc does not have a concept of a base indentation level within a comment. If any line in this comment format is 4 or more spaces from the left it will be rendered as an example block. Yikes!

/**
    This method does something very useful.

    The following example shows an appropriate use of `doSomething`

        NSLog(@"%@", thing.someProperty);  // Logs "A"
        [thing doSomething];
        NSLog(@"%@", thing.someProperty);  // Logs "B"
 */
- (void)doSomething;

Documentation with indented whitespace prefix

Finally, this is very important, if you have been relying on indentation to offset example code in Appledoc comments without a /// or * prefix, know that XCode has no interest in preserving your indentation. If you ever try to copy and paste those comments or use the Reindent option on your code, Xcode will align everything in the comment to the same column as the first star in the comment opening. Combined with the fact that the star prefix does not parse properly in Appledoc, this is why I use /// as a prefix.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment