Automatic symbol linking should be more strict. #135

lhunath opened this Issue Aug 30, 2011 · 7 comments

3 participants


Currently, the code that tries to automatically determine what words in a comment sentence should be linked to methods or other symbols is too lax. This causes links to appear in the documentation on words that are just language and no reference to code symbols all over the place.

A common scenario is when I write a sentence such as "to initialize the class, use the -initWithName: method and pass in your user's name", and I get a link on the "initialize" word to the class' +initialize method.

Links should only be created for words that are prefixed with either a + or a -, or perhaps also those that begin/contain capitals. It is widely accepted that to reference a method, you prefix it with a - if it's an instance method and a + if it's a class method (and appledoc already supports this).

Alternatively, if for some reason ("backwards compatibility"?) it is deemed unacceptable to do this by default, there should be an option to make this matching more strict.

@tomaz tomaz closed this Aug 31, 2011

I find the solution I propose better by far to the solution proposed on that page. There is no need for making <> markers required when you go off of + and -. Also, +moo should only become a link if there is a class-method moo, and not when moo is an instance method. You cannot express that using a custom cross-reference format. Implementing the suggestions above will make things far easier for users and will make things work right by default, instead of broken by default. Right now, the options are either broken or complicated. I like neither.


You don't have to rely on <>, that's just what --explicit-crossref does, by using --crossref-format you can setup whatever regular expression you like, including +/- prefix, you can get quite creative that way, although there are some restrictions to it, check the docs. Of course this would only cover methods, not properties, classes and categories, so you'd want to make the prefix optional. You'd probably end with warnings but you can suppress them through cmd line switches. These two options were added after initial 2.0 has been released, so I didn't want to change behavior dramatically for existing users, hence defaults stayed the same. For new users this might seem broken as you say, perhaps I could change defaults in next larger release, 2.1 for example, as these have been around for a while now.

I always strive for 80/20 solution. Hence default options are tuned to let you quickly start writing documentation expressing it in as natural way as possible. Appledoc is very versatile tool and likely each developer would like to use it in her own special way. Therefore I left doors open for customization to some extent through cmd line switches. And if you find you use certain sets of switches frequently, you can save them to global settings file. Alternatively, when you're creating a single project that should use different settings, for example for a particular client who demands certain format, you can override globals through project settings file and/or cmd line, whichever way you prefer.

Finally, there's complete source code available, so if none of available tools are sufficient, you could tweak the code to your needs as the last resort. There were couple of people extending the tool in the past, some for their personal/company needs, some in generic way that I could merge back into the main branch. In any case I've always helped them with directions and answers, so feel free to contact me if you choose this path!


I actually don't think I can even use --crossref-format to solve this issue at all.

I could use a format "[+-]%@", but then no classes would get matched. I don't know if I can cheat my way in using ([A-Z]%@) instead of %@, but that seems very hacky and dependent on what %@ ends up doing. I can't make it optional, as you say, because then I have the exact same problem as I have just filed the issue for; a problem caused by the < and > being optional by default and the %@ not requiring the - or +.

I see only one way to solve this issue, and that's by updating the source code. I don't mind, you'll notice I've also contributed the --exclude-output code. But I'll need to find some time to fit it in.


Sure, I'd love to do more work on appledoc too but am too busy at this point, currently I'm only taking smaller fixes and features... Will mark this as a feature request to not forget about it.

Some random thoughts for implementation, now I'm at the issue - for whoever will take it in the future:

  • The quickest solution might be simply restricting checking for method cross refs if no prefix is given.
  • Protocols, classes, categories and properties would still have to be checked.
  • Probably the best solution would be adding method matching regex in addition to other and use it when detecting crossrefs.
    • This could be implemented so that it would fall-back to old style based on cmd line,
    • Perhaps --explicit-crossref could be used to change all regexes appropriately.
    • It might be nice to extend --crossref-format to provide all possible regexes not just one, separated by some symbol.

Oh, GitHub didn't show avatars before, but now I remember you, you have way too cryptic username for me to store to my "mental" HD :)

@tomaz tomaz reopened this Aug 31, 2011

Old issue, and I see you've made progress in #180 (although I've yet to manage to compile the experimental branch and try it out). But I've been thinking a lot about this over the past few days while fighting with crossrefs, and it seems to me that automatic linking isn't currently worth the associated costs.

Manual crossrefs have repeatedly failed for me (with workaround attempts often also failing), so I've fallen back to using automatic crossrefs, but these come at the cost of things like the string "multiline text" having the substring line erroneously linked to the method +[MGLine line]. Not pretty, and I'm currently at a loss for how to stop it (other than going back to manual crossrefs, which don't work for me in ~50% of cases).

The approach of manual crossrefs with a single char prefix does seem rather ideal. No more erroneous links that can't be removed, and markup so simple that eliminates the benefits of automatic crossrefs.

I'm imagining something like:

  • local +classMethod
  • local -instanceMethod and -property
  • local [description](+classMethod)
  • local [description](-instanceMethod) and [description](-property)
  • remote +[ClassName classMethod]
  • remote -[ClassName instanceMethod] and -[ClassName property]
  • remote [description](+[ClassName classMethod])
  • remote [description](-[ClassName instanceMethod]) and [description](-[ClassName property])

If I manage to get up to speed on the experimental branch I'm slightly tempted to code this up, as I've got a free week on my hands. But it's a bit of a long shot, and best to figure out whether I'm in line with the project's goals first anyway.


What you describe is supported on experimental branck (at least think so, don't remember if I actually finished it, it's few weeks since I worked on it).

You should be able to compile experimental branck now too - until few days ago it was broken for everyone but me because I forgot to include .xcworkspace bundles (these extensions were ignored in my gitignore file, remant of old Xcode 2 & 3 days :) However you won't see results yet (but you can take a look at unit tests to get an idea what is and isn't supported - you should find 3.0 code much more readable and better structured IMHO :)

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