Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Macro-decorated properties are documented with the wrong name. #373

Open
groue opened this Issue · 18 comments

4 participants

@groue

Hi,

This issue is as side effect of CocoaPods/CocoaPods#1204.

The following method, declared at https://github.com/groue/GRMustache/blob/v6.7.4/src/classes/GRMustacheConfiguration.h#L157:

@property (nonatomic, retain) GRMustacheContext *baseContext AVAILABLE_GRMUSTACHE_VERSION_6_4_AND_LATER;

Is outputted by appledoc as (see for instance http://cocoadocs.org/docsets/GRMustache/6.7.4/Classes/GRMustacheConfiguration.html#//api/name/AVAILABLE_GRMUSTACHE_VERSION_6_4_AND_LATER):

@property (nonatomic, retain) GRMustacheContext *AVAILABLE_GRMUSTACHE_VERSION_6_4_AND_LATER

The property has, unfortunately, lost its name (and the macro should not appear in the doc).

http://github.com/groue/GRMustache actually uses those macros to decorate:

I use them to be able to keep alive the tests for deprecated but not-yet removed methods, without getting any warning - they are quite useful, actually.

Thanks for the good work :smile: (BTW the latest GRMustache is really faster than the one you are using, you may consider upgrading)

@paulmelnikow

Re your BTW: Do you know if the latest version of GRMustache works with garbage collection? If not I think the project will need to be ARC-ified first.

@groue

GRMustache is explicitly tested under GC, ARC-compatible, and does not require to be ARC-ified to integrate into any project.

I've looked at appledoc sources. Here are the old APIs that you would need to migrate:

  • GBDictionaryTemplateLoader is now built-in (you can drop this class entirely, and use +[GRMustacheTemplateRepository templateRepositoryWithDictionary:])
  • -[GBDictionaryTemplateLoader parseString:error:] is replaced by -[GRMustacheTemplateRepository templateFromString:error:]
  • -[GRMustacheTemplate renderObject:] is replaced by -[GRMustacheTemplate renderObject:error:]
  • syntax-wise, the slash in {{ foo/bar }} tags has been replaced by the dot, as in {{ foo.bar }}
@tomaz
Owner

Is this still an issue with latest code? I merged pull request addressing some of output formatting problems.

@groue

Yes, the issue is still here, using appledoc 2.1 (build 858), installed from the latest master branch (ba1083e) and sh install-appledoc.sh -t default command.

@groue

The newly introduced support for enums are affected, too.

The following code:

/**
 * The codes of a GRMustache-generated NSError
 *
 * @since v1.0
 */
typedef NS_ENUM(NSInteger, GRMustacheErrorCode) {
    /**
     * The error code for parse errors.
     *
     * @since v1.0
     */
    GRMustacheErrorCodeParseError AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER,

    /**
     * The error code for not found templates and partials.
     *
     * @since v1.0
     */
    GRMustacheErrorCodeTemplateNotFound AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER,

    /**
     * The error code for not rendering errors.
     *
     * @since v6.3
     */
    GRMustacheErrorCodeRenderingError AVAILABLE_GRMUSTACHE_VERSION_6_3_AND_LATER,

} AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER;

Is documented as (6 values in the enum instead of 3, and mangled doc strings):

Definition

typedef NS_ENUM(NSInteger, GRMustacheErrorCode ) {
   GRMustacheErrorCodeParseError,
   AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER,
   GRMustacheErrorCodeTemplateNotFound,
   AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER,
   GRMustacheErrorCodeRenderingError,
   AVAILABLE_GRMUSTACHE_VERSION_6_3_AND_LATER,
};

Constants

  • GRMustacheErrorCodeParseError

    The error code for parse errors.
    Available in v1.0
    Declared In GRMustacheError.h.
    
  • AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER

    The codes of a GRMustache-generated NSError
    Available in v1.0
    Declared In GRMustacheError.h.
    
  • GRMustacheErrorCodeTemplateNotFound

    The error code for not found templates and partials.
    Available in v1.0
    Declared In GRMustacheError.h.
    
  • AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER

    The codes of a GRMustache-generated NSError
    Available in v1.0
    Declared In GRMustacheError.h.
    
  • GRMustacheErrorCodeRenderingError

    The error code for not rendering errors.
    Available in v6.3
    Declared In GRMustacheError.h.
    
  • AVAILABLE_GRMUSTACHE_VERSION_6_3_AND_LATER

    The codes of a GRMustache-generated NSError
    Available in v1.0
    Declared In GRMustacheError.h.
    

Availability

v1.0

@groue

Note that enums with values are better handled:

/**
 * The types of Mustache tags
 *
 * @since v6.0
 */
typedef NS_ENUM(NSUInteger, GRMustacheTagType) {
    /**
     * The type for variable tags such as {{ name }}
     *
     * @since v6.0
     */
    GRMustacheTagTypeVariable = 1 << 1 AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER,

    /**
     * The type for section tags such as {{# name }}...{{/}}
     *
     * @since v6.0
     */
    GRMustacheTagTypeSection = 1 << 2 AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER,

    /**
     * The type for overridable section tags such as {{$ name }}...{{/}}
     *
     * @since v6.0
     */
    GRMustacheTagTypeOverridableSection = 1 << 3 AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER,

    /**
     * The type for inverted section tags such as {{^ name }}...{{/}}
     *
     * @since v6.0
     */
    GRMustacheTagTypeInvertedSection = 1 << 4 AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER,
} AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER;

Is documented with 4 values, not 8, unlike the GRMustacheErrorCode enum above. Macros are still visible in the documentation, though.

@tomaz
Owner

Yea, parsing is not exact in appledoc, I was looking into using clang, but it felt too exact for such needs. Will take a look once I finish my current work.

@robvdveer
Collaborator

I'll pick this one up, if you don't mind, since i'm the one responsible... (The issues with the macro mismatch)

@tomaz
Owner

Sure, go ahead

@robvdveer
Collaborator

Any suggestions on how to detect macros without having to parse all include/import statements? Can i safely assume all uppercase is a macro? What about parametrised macros? If this is the case, a simple check would do to 'eat away' the capiltalized tokens

@groue

I'd assume that all macros are stuff that can be ignored after the longest documentation item has been identified:

After MACRO; has been parsed, no method has been identified (missing colon between MACRO and ;), so the identified method is blah:foo::

- (void)blah:(int)a foo:(int)b MACRO;

After the last ) has been parsed, the name property has been totally identified, and everything else can be ignored:

@property (nonatomic,copy) int(^name)(int arg) __attribute__((deprecated));

After name1, value, and } have been parsed, the name1, name2 and foo enum values and enum has been identified, and everything else can be ignored:

enum foo {
    name1 MACRO,
    name2 = value MACRO,
} MACRO;

What do you think?

This technique would avoid dangerous assumptions like uppercase macros.

@robvdveer
Collaborator
@groue

Not an easy job, you're right.

@robvdveer
Collaborator

Should the MACRO directives persist in the documentation? I am now able to parse the NS_ENUM declarations by filtering the all uppercase words. Sample:

#define AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER

typedef NS_ENUM(NSUInteger, GSEnumDemo)
{
    One,
    Two AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER,
    Three = 3,
    Four AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER = 4,
    Five = 1 << 5 AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER,
    Six = AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER 1 << 6,
    Seven
} AVAILABLE_GRMUSTACHE_VERSION_6_0_AND_LATER;

This will result in the documented:


Definition
typedef NS_ENUM(NSUInteger, GSEnumDemo ) {
   One,
   Two,
   Three = 3,
   Four = 4,
   Five = 1 < < 5,
   Six = 1 < < 6,
   Seven,
};

I added a method to the parser called 'consumeMacro' perhaps i can reuse it for the method declarations (changes pushed to my fork)

@tomaz
Owner

I think it's a valid assumption for most cases.

@robvdveer
Collaborator

That last push #381 fixed the behavior for NS_ENUM that was just introduced, but I didn't dare touching the other parsing code.

@tomaz
Owner

Cool, is this fixed then, can I close the issue?

@robvdveer
Collaborator

No, the push only fixed macros for NS_ENUM, not for properties as in the original poster request

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.