Deprecating methods in documentation #80

Open
poussain opened this Issue Mar 10, 2011 · 12 comments

Comments

Projects
None yet
6 participants
@poussain

Hi Tomaz !

It's really cool what you do, Appledoc is just beautiful !
There is an option I'd really like : in the iPhone SDK, some methods are "deprecated", and as my company sells a library, I'd mark some methods as "deprecate" in my code like this:

  • (void)oldMethod attribute((deprecated));

This will inform the developer with a "Warning : 'oldMethod' is deprecated". In the Apple documentation, those methods have a red "Deprecated" labelI. It would be really nice to have this option in Appledoc !

For the moment, I use @bug Warning this method is deprecated, but it's not visible until the developer reads the documentation (if he only looks at the titles he won't see it).

@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz Mar 10, 2011

Owner

This is already in the list - see #9, will leave this issue open as it's likely going to be implement separately.

Owner

tomaz commented Mar 10, 2011

This is already in the list - see #9, will leave this issue open as it's likely going to be implement separately.

@beelsebob

This comment has been minimized.

Show comment Hide comment
@beelsebob

beelsebob May 15, 2011

Contributor

I'd like to put in a vote for this, but with an extra note – typically apple's docs give a recommended method to use instead of the deprecated method, an "@deprecated blah goes here" in the comments would probably be needed as well as the attribute in the code.

Contributor

beelsebob commented May 15, 2011

I'd like to put in a vote for this, but with an extra note – typically apple's docs give a recommended method to use instead of the deprecated method, an "@deprecated blah goes here" in the comments would probably be needed as well as the attribute in the code.

@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz May 25, 2011

Owner

I'm also thinking in @deprecated direction to allow adding description and use-instead information. It's much more useful than just marking a method deprecated.

Owner

tomaz commented May 25, 2011

I'm also thinking in @deprecated direction to allow adding description and use-instead information. It's much more useful than just marking a method deprecated.

@onekiloparsec

This comment has been minimized.

Show comment Hide comment
@onekiloparsec

onekiloparsec Jul 18, 2011

I also would like to put a vote for this. Actually, I've downloaded the sources, and as far as I can see, there is no progresses in this direction yet. Am I right? I would love to have even a basic support for @deprecated with a red-color section. Thanks anyway for the very impressive work. The visual quality of the output is just perfect.

I also would like to put a vote for this. Actually, I've downloaded the sources, and as far as I can see, there is no progresses in this direction yet. Am I right? I would love to have even a basic support for @deprecated with a red-color section. Thanks anyway for the very impressive work. The visual quality of the output is just perfect.

@onekiloparsec

This comment has been minimized.

Show comment Hide comment
@onekiloparsec

onekiloparsec Jul 18, 2011

Just an additional notes on this. I've seen that there is parsing support to ignore any pieces like that attribute((anything)). However, when distributing a library, I prefer to make a macro something like NS_DEPRECATED which then check if the attribute thing is available and other formating things before inserting the true attribute code.

Supporting this isn't so easy I guess. I succeeded to tweak the sources by hard-coding the name of my macro at the places where attribute must be skipped.

And then, there is this @deprecated comment that would be extremely nice. These are two different, though related, things.

Just an additional notes on this. I've seen that there is parsing support to ignore any pieces like that attribute((anything)). However, when distributing a library, I prefer to make a macro something like NS_DEPRECATED which then check if the attribute thing is available and other formating things before inserting the true attribute code.

Supporting this isn't so easy I guess. I succeeded to tweak the sources by hard-coding the name of my macro at the places where attribute must be skipped.

And then, there is this @deprecated comment that would be extremely nice. These are two different, though related, things.

@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz Jul 26, 2011

Owner

I'm ignoring attribute thing due to having issues with it in the past. Using macros is surely nicer for handling the source code, but would be much more challenging - it would effectively require doing preprocessing over source files for #define, #ifdefs etc. So for the moment I don't want to step down this road (you could update the code for your specific case though). So @deprecated seems to be the way to go for now.

Oh, forgot to reference to #9 which is my note for superset of deprecated functionality. It seems like small effort to bring in additional features besides deprecated.

Owner

tomaz commented Jul 26, 2011

I'm ignoring attribute thing due to having issues with it in the past. Using macros is surely nicer for handling the source code, but would be much more challenging - it would effectively require doing preprocessing over source files for #define, #ifdefs etc. So for the moment I don't want to step down this road (you could update the code for your specific case though). So @deprecated seems to be the way to go for now.

Oh, forgot to reference to #9 which is my note for superset of deprecated functionality. It seems like small effort to bring in additional features besides deprecated.

@smartcat32

This comment has been minimized.

Show comment Hide comment
@smartcat32

smartcat32 Jul 16, 2012

Has there been any progress on @deprecated? If it's not coming soon, could you provide any tips on what to modify to add @deprecated support and/or any known obstacles? Thanks!

Has there been any progress on @deprecated? If it's not coming soon, could you provide any tips on what to modify to add @deprecated support and/or any known obstacles? Thanks!

@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz Jul 17, 2012

Owner

Not yet, I'm focusing on major upgrade whenever I get some time (experimental branch). I'm not planning to add this at start, but will most likely come in a later update, after startup issues calm down.

You can most definitely take a look - this should be straightforward implementation although would require tweaking several parts of the system: first parsing to detect the directive, then storing the flag in store classes and finally rendering it via html templates. If you have concrete questions, contact me through email or appledoc Google group.

Owner

tomaz commented Jul 17, 2012

Not yet, I'm focusing on major upgrade whenever I get some time (experimental branch). I'm not planning to add this at start, but will most likely come in a later update, after startup issues calm down.

You can most definitely take a look - this should be straightforward implementation although would require tweaking several parts of the system: first parsing to detect the directive, then storing the flag in store classes and finally rendering it via html templates. If you have concrete questions, contact me through email or appledoc Google group.

@paynerc

This comment has been minimized.

Show comment Hide comment
@paynerc

paynerc Jan 17, 2013

@smartcat32 Have you made any tweaks to add this? We are working on an SDK and I need to deprecate some things and it sure would be handy!

paynerc commented Jan 17, 2013

@smartcat32 Have you made any tweaks to add this? We are working on an SDK and I need to deprecate some things and it sure would be handy!

@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz Jan 17, 2013

Owner

I'm thinking about it for 3.0 branch (with unfortunate name experimental :) but not on master branch (2.x)...

Owner

tomaz commented Jan 17, 2013

I'm thinking about it for 3.0 branch (with unfortunate name experimental :) but not on master branch (2.x)...

@paynerc

This comment has been minimized.

Show comment Hide comment
@paynerc

paynerc Jan 17, 2013

How stable is the experimental branch? Any timeframe on when a 3.0 release would ship?

paynerc commented Jan 17, 2013

How stable is the experimental branch? Any timeframe on when a 3.0 release would ship?

@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz Jan 17, 2013

Owner

It's stable at what it does, and it does quite a lot already, but not generating any output yet :) I'm working on it whenever I get a chance but find it hard to get a larger frame of time when I can devote to it 100% due to my obligations. Consequently progress is on the slow side. Due to this unpredictability, I also can't give you estimate on when it will be ready... I'm also eager to get it out there as fast as possible as current codebase is quite patchy and fragile, so new one should reduce my workload.

Owner

tomaz commented Jan 17, 2013

It's stable at what it does, and it does quite a lot already, but not generating any output yet :) I'm working on it whenever I get a chance but find it hard to get a larger frame of time when I can devote to it 100% due to my obligations. Consequently progress is on the slow side. Due to this unpredictability, I also can't give you estimate on when it will be ready... I'm also eager to get it out there as fast as possible as current codebase is quite patchy and fragile, so new one should reduce my workload.

@boundsj boundsj referenced this issue in mapbox/mapbox-gl-native Aug 22, 2015

Closed

Introduce MGLConfigurationManager #2154

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