Support for #pragma mark as alternate to @name #108

Open
barneym opened this Issue May 25, 2011 · 15 comments

Comments

Projects
None yet
7 participants

barneym commented May 25, 2011

A suggestion...

For those that use "#pragma mark ..." to section out code blocks for collapsing, it would be a nice feature to be able to honor these lines as an alternative to using the @name.

This probably violates a dozen OC/JavaDoc guidelines, but having to comment the #pragma looks pretty tacky.

For parsing purposes, I would also note that these come in a few common variations:

pragma mark some section

OR

pragma mark -

pragma mark some section

OR 

pragma mark - some section

Barney

Owner

tomaz commented May 25, 2011

Cool - I like this, great idea! I use #pragma mark all the time, but it never occurred to me to use it for grouping as well.

I comment methods in header file and I want to keep them grouped there (at least visually), so I use @name which keeps the same formatting. And of course I want to keep methods grouped in my implementation files too, so I use #pragma mark. Will experiment a bit to see how this would work best together. In the worst case it would be either one or the other...

barneym commented May 28, 2011

I struggle with the header versus body commenting all the time. The header obviously needs to get documented for API reuse, but I'm also commenting all of my internal methods to insure I have good reference for where I was going, design thoughts, or subclassing concerns. I tend to do all of my documentation in the implementation and then either just add internal guidance commentary in the header files (trying to mimic Apple's approach) or move those comments that are appropriate out to the header.

I can definitely see where this would break down if you use different groupings in the header than in the implementation, which is probably not uncommon. I could see header having pragmas just to allow collapsing property/method areas or having functional breakdowns. My personal preference would be to favor the implementation, but a thorny question I agree. Though technically the problem should exist with @name even now between the header/implementation.

Owner

tomaz commented May 29, 2011

That was also one of my first thoughts. Even with @name, using it in both header and implementation would lead to unpredictable results in certain cases. But as @name is explicit, this isn't such an issue. With #pragma, it would need to be handled more intelligently...

I think header/implementation documentation is a matter of taste. Personally I keep it in header as implementation is already verbose with all the code. This makes header harder to read, but I rarely do that due to Xcode navigation bar, so it's good compromise for me. Documenting internal documentation is also a matter of preference. I just write inline comment if I think necessary. All in all, documenting is one of the topics people have various opinions on, some even arguing it's waste of time and code should be written so that it conveys the purpose. It also depends on whether you're documenting a reusable framework or application - first definitely requires more work on documentation too.

+1 for #pragma support. Documentation is something that no one does the same way, I for one need to document the private parts as well because I'm preparing to hand off my project to other developers. Right now this leaves me with a lot of methods collected under "Other methods", which looks odd (screenshot). Because the project is already using #pragma very often, it'd be awesome to have that extracted and the methods categorized accordingly. As for the merging header/implementation, I could see the header sections being on top, and the implementation sections below.

P.S. Sorry for the high traffic, Tomaz, I'm just really enjoying the fact that I can finally generate proper documentation from my code comments!

Owner

tomaz commented Jun 27, 2011

You can use @name sections within extensions and categories the same way as in classes, even if they are merged to their class docs, you can control this with --keep-merged-sections and --prefix-merged-sections, described here.

When #pragma grouping will be implemented, it'll use the same mechanism.

PS: Don't worry for high traffic, it's what brings new ideas and direction to the project :)

Seems that these flags (0/0, 0/1, 1/0 nor 1/1) do not change the repeated mentioning of "Other Methods" see screenshot in my previous comment. Where does that come from then?

Owner

tomaz commented Jun 27, 2011

Hm, that might be an issue, will check it.

soffes commented Jul 4, 2011

I love this feature. Please do it :)

I'd also like this feature, so another + 1 from me.

+1. Would be a great feature.

rdlopes commented Mar 6, 2012

+1, that would be great.
At the moment, my code is cluttered with ugly statements like

/** @name Class Factories */
#pragma mark - Class Factories

If I could have just the nice #pragma mark - Class Factories that would prevent me from forgetting either one or the other, always a pain when having lots of documentation (I should be rewarded for documenting, not punished^^)

Owner

tomaz commented Mar 8, 2012

Just a notice - while fixing #199 I realized that using #pragma mark after @name makes appledoc "forget" about the section resulting in "Other methods" output in certain situations (merging documentation from adopted protocols for example). The only workaround in such case is the change the order and put #pragma mark before like this:

#pragma mark - Class Factories
/** @name Class Factories */

rdlopes commented Mar 8, 2012

Nice one! Thanks a lot, was really getting confused about how to make it work.

Owner

tomaz commented Apr 13, 2012

Included this for next major update - you can follow progress on experimental branch (currently only prints out all known symbols, doesn't do anything useful yet).

Owner

tomaz commented Aug 25, 2012

Quick update: 3.0 is already parsing pragma mark as sections.

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