Method task section is not created under certain circumstances #76

Closed
tomaz opened this Issue Mar 2, 2011 · 2 comments

Projects

None yet

1 participant

@tomaz
Owner
tomaz commented Mar 2, 2011

This code:

/// @name title

- (void)method1;

/** comment */
- (void)method2;

will not create task section "title"; instead it will simply continue previous section. The same happens if method1 is commented with "standard" comment /* */. The reason for this is resetting comments in GBTokenizer after matching valid object (method1).

@tomaz
Owner
tomaz commented Mar 3, 2011

Turns out the above example actually works, but it doesn't work if there's some text before @name like this:

///----------------------------
/// @name name

As delimiters are stripped after checking for @name, this comment isn't accepted as @name section and is instead treated as normal comment for the next method. Fix on the way...

@tomaz
Owner
tomaz commented Mar 3, 2011

Fixed @name handling when followed by uncommented method. Closed by 90e3553.

The problem was in the way comments were being processed. If any comment contained @name, it was always used for creating a new task section, even if followed by uncommented method. However delimited comments:

///--------------------
/// @name Something
///--------------------

Were not correctly detected as @name comments. The reason was in the regex being used for matching @name: it expected the @name at the start of the comment string. By changing the regex to match in any line, this works correctly. The downside is that section names spanning multiple lines are now ignored (you can delimit @name and first word by new line though). On the other hand, I don't think anybody uses section names in such a way, so it'll probably work just fine.

Proper solution would require using two regexes: one for matching @name before stripping delimiters and one for matching afterwards. Or alternatively strip delimiters immediately after recognizing a comment (at present this is all delayed until needed to make the tool as efficient as possible).

@tonklon tonklon pushed a commit to tonklon/appledoc that referenced this issue Mar 8, 2012
@tomaz Fixed @name handling when followed by uncommented method. Closes #76.
The problem was in the way comments were being processed. If any comment contained @name, it was always used for creating a new task section, even if followed by uncommented method. However delimited comments:

	///--------------------
	/// @name Something
	///--------------------

Were not correctly detected as @name comments. The reason was in the regex being used for matching @name: it expected the @name at the start of the comment string. By changing the regex to match in any line, this works correctly. The downside is that section names spanning multiple lines are now ignored (you can delimit @name and first word by new line though). On the other hand, I don't think anybody uses section names in such a way, so it'll probably work just fine.

Proper solution would require using two regexes: one for matching @name before stripping delimiters and one for matching afterwards. Or alternatively strip delimiters immediately after recognizing a comment (at present this is all delayed until needed to make the tool as efficient as possible).
90e3553
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment