Added extra options to exclude symbols, and local auto-generated cross-references

[antmd]

Hi,

I want to use appledoc to generate documentation for a large project, and it works very well (thanks for writing it!).

I had two issues, which this pull request addresses.

1. The project has some categories with the name 'Deprecated', which should not appear in the final documentation. Doxygen has an option to ignore symbols (as well as files). This change adds an argument '--ignore-symbol', which takes a 'glob' argument (e.g. 'Deprecated'). If that glob matches any class, protocol, extension or category, then that symbol will not appear in the final output.
2. As other people have found (reading your past issues), sometimes appledoc can create false links to local symbols if those local symbols are common words such as 'and'. However, auto-linking of cross-references is very useful. I tried the explicit-crossrefs argument, but that had several problems. Instead, This change adds an argument '--require-leader-for-local-crossrefs', which works well for my case, and I think it is useful in general. When this is supplied as an argument, auto-linking of local cross-references only happens when the symbol name appears with a leading '-' or '+'

I have also added two test cases for the new arguments.

Best Regards
--Anthony

[robvdveer]

Looks great, thanks for your suggestion. I'll leave it to tomaz to merge this pull request.

Does this update also affect the recent additions of NS_ENUM constants?
And how would i use a local crossreference to a class property? (that has no '-' or '+' prefix)

[antmd]

Hi

Does this update also affect the recent additions of NS_ENUM constants?
And how would i use a local crossreference to a class property? (that has no '-' or '+' prefix)

if you use the new --require-leader-for-local-crossrefs flag, either you have to add a prefix ('leader') of '-' or '+' (it will be stripped in the final docs), or the property/enum value will not be auto-linked.

In the case of local references that might be auto-linked simply by matching a word, a manual marker is the only way to reduce false-positives.

As the new flag is not the default, it will not affect current appledocs.

We could add other leaders for properties and enums (e.g. '@' or '=', or both), bearing in mind that the different leaders are there for readability of the 'raw' comments -- they will all be treated the same by appledoc.

Another change that I think would help would be to check for word-boundaries for auto-linking local references: at the moment, auto-linking will happen even if the symbol name is embedded in a word! I was using this to generate docs for ReactiveCocoa, which has symbols 'and' 'or', 'from', etc. That highlighted every 'and', even when it was part of another word, e.g. 'brand'.

Best
--Anthony

On 31 Aug 2013, at 21:10, robvdveer [email protected] wrote:

Looks great, thanks for your suggestion. I'll leave it to tomaz to merge this pull request.

Does this update also affect the recent additions of NS_ENUM constants?
And how would i use a local crossreference to a class property? (that has no '-' or '+' prefix)

—
Reply to this email directly or view it on GitHub.

[tomaz]

Cool, thanks!

Although - is not too bad for for non-methods, I agree with @robvdveer - it would be nice to have other prefixes. I wouldn't use @ because it may interfere with parameters - @param and company. =, ~ and # pop to my mind (last one might be too distracting when reading comments)... Would be nice if you can append this, will give you some time :) but otherwise will just merge!

In this moment I don't remember why I used char-boundary detection, there is word boundary detection in there. I was probably hitting some edge cases.

Tom

[antmd]

Hi Tom

I can do the change this weekend (bit busy this week).

another option for a leader/prefix (in regex-speak): \b(?:self)?\.

i.e., self.<property> or just .<property>

Happy to take a vote!

--Anthony

[robvdveer]

I believe charbound detected was used for cases where a token needs to be detected inside a code fragment. In a previous session, i already noticed that and suggested it to be token-based, not character based.

—

http://simplicate.weebly.com

On Tue, Sep 3, 2013 at 1:09 AM, Whirliwig [email protected]
wrote:

Hi Tom
I can do the change this weekend (bit busy this week).
another option for a leader/prefix (in regex-speak): \b(?:self)?\.
i.e., self.<property> or just .<property>
Happy to take a vote!

--Anthony

Reply to this email directly or view it on GitHub:
#397 (comment)

[tomaz]

If you make the option take regex (similar to --crossref-format but limited to local refs), then it becomes quite universal. It can optionally take %@ placeholder, just like crossref format and if it's present you assume it's regex, otherwise it's just plain prefix. Although in this case, it might be better to extend --crossref-format to optionally accept multiple formats using some delimiter to make cmdline simpler - if there's single format, it's for all, if two, second is for local refs, first for the rest (for example --crossref-format "/%@/-%@/", or --crossref-format "/%@/-/" if using plain previx. In both cases I used / as delimiters for two formats which must be present at start, end and to delimit both regexes). Just an idea - do whatever suits you and your time better :)

[tomaz]

@robvdveer I totally agree - comment preprocessing desperatly needs update. It's hacky partially due to how discount (Markdown library used to produce html) works. Originally I used custom Markdown parsing and it was much cleaner, but missing features, especially for static documents, so I eventually replaced it with more feature-rich library but lost feedback for type of blocs certain text belongs to (primarily code blocks which should be left untouched). I played with sundown library for 3.0 which has callbacks so I can only process stuff when outside code blocks etc.