As you may, or may not know, the next release will start to generate documentation of every lib by default. It uses the `appledoc` tool for this [1]. One minor issue, I found, is that if a lib does not contain any explicit appledoc comments, than the selectors in the docs won’t contain param type info. (See screenshot [2].)
(The Markdown formatted README’s are just beautiful imho :) See screenshot [3].)
I _think_ this should be fairly straightforward to add and would love to have that in appledoc before we release 0.6.
So the big question is, is anyone here interested in looking into this? As it’s written in Objective-C, this could be an excellent way to help out without having to know Ruby.
> As you may, or may not know, the next release will start to generate > documentation of every lib by default. It uses the `appledoc` tool for this > [1]. One minor issue, I found, is that if a lib does not contain any > explicit appledoc comments, than the selectors in the docs won’t contain > param type info. (See screenshot [2].)
> (The Markdown formatted README’s are just beautiful imho :) See screenshot > [3].)
> I _think_ this should be fairly straightforward to add and would love to > have that in appledoc before we release 0.6.
> So the big question is, is anyone here interested in looking into this? As > it’s written in Objective-C, this could be an excellent way to help out > without having to know Ruby.
> Hi, Eloy. > I'm relatively free this week and next week, so I can look at at it.
> четверг, 12 апреля 2012 г., 13:15:34 UTC+3 пользователь Eloy Durán написал: > Hey guys, > As you may, or may not know, the next release will start to generate documentation of every lib by default. It uses the `appledoc` tool for this [1]. One minor issue, I found, is that if a lib does not contain any explicit appledoc comments, than the selectors in the docs won’t contain param type info. (See screenshot [2].)
> (The Markdown formatted README’s are just beautiful imho :) See screenshot [3].)
> I _think_ this should be fairly straightforward to add and would love to have that in appledoc before we release 0.6.
> So the big question is, is anyone here interested in looking into this? As it’s written in Objective-C, this could be an excellent way to help out without having to know Ruby.
> As you may, or may not know, the next release will start to generate > documentation of every lib by default. It uses the `appledoc` tool for this > [1]. One minor issue, I found, is that if a lib does not contain any > explicit appledoc comments, than the selectors in the docs won’t contain > param type info. (See screenshot [2].)
> (The Markdown formatted README’s are just beautiful imho :) See screenshot > [3].)
> I _think_ this should be fairly straightforward to add and would love to > have that in appledoc before we release 0.6.
> So the big question is, is anyone here interested in looking into this? As > it’s written in Objective-C, this could be an excellent way to help out > without having to know Ruby.
> I'm not sure if we need to display other classes and protocols as a links. appledoc mimics references at developer.apple.com and method declarations displayed there as a plain text.
> I’m not following completely, can you elaborate?
Suppose we have three classes:
@interface ClassA
@end
@interface ClassB
@end
@interface ClassC
-(ClassA*)someMethod:(ClassB*)b ;
@end
Doc for someMethod will contain only method declaration in plain text. Alternative, we can make ClassA and ClassB link to appropriate documentation pages for this classes.
I would personally very much like them to link, though, but that’s up to the authors of appledoc. Maybe ask them about it in the pull-request for your commit?
On Fri, Apr 13, 2012 at 10:20 AM, SevInf <inferna...@gmail.com> wrote:
>> I’m not following completely, can you elaborate?
> Suppose we have three classes:
> @interface ClassA
> @end
> @interface ClassB
> @end
> @interface ClassC
> -(ClassA*)someMethod:(ClassB*)b ;
> @end
> Doc for someMethod will contain only method declaration in plain text. > Alternative, we can make ClassA and ClassB link to appropriate documentation > pages for this classes.
On Fri, Apr 13, 2012 at 10:35 AM, Eloy Duran <e...@dekleineprins.me> wrote: > Ah I see. As you say, the appledoc style is to do what Apple does, and > as you can see from an appledoc output example, they do not link them:
> I would personally very much like them to link, though, but that’s up > to the authors of appledoc. Maybe ask them about it in the > pull-request for your commit?
> On Fri, Apr 13, 2012 at 10:20 AM, SevInf <inferna...@gmail.com> wrote:
>>> I’m not following completely, can you elaborate?
>> Suppose we have three classes:
>> @interface ClassA
>> @end
>> @interface ClassB
>> @end
>> @interface ClassC
>> -(ClassA*)someMethod:(ClassB*)b ;
>> @end
>> Doc for someMethod will contain only method declaration in plain text. >> Alternative, we can make ClassA and ClassB link to appropriate documentation >> pages for this classes.
Thanks.
I've asked appledoc authors about adding links to method prototypes. It's planned and there is already an issue for this https://github.com/tomaz/appledoc/issues/17 So, I'll take a look at it, but I'm not sure how long will it take.
пятница, 13 апреля 2012 г., 13:32:01 UTC+3 пользователь Eloy Duran написал:
> Btw, just installed your fork and re-generated my docs; it’s sooo much
> better now :)
> On Fri, Apr 13, 2012 at 10:35 AM, Eloy Duran <e...@dekleineprins.me> > wrote:
> > Ah I see. As you say, the appledoc style is to do what Apple does, and
> > as you can see from an appledoc output example, they do not link them:
> > I would personally very much like them to link, though, but that’s up
> > to the authors of appledoc. Maybe ask them about it in the
> > pull-request for your commit?
> > On Fri, Apr 13, 2012 at 10:20 AM, SevInf <inferna...@gmail.com> wrote:
> >>> I’m not following completely, can you elaborate?
> >> Suppose we have three classes:
> >> @interface ClassA
> >> @end
> >> @interface ClassB
> >> @end
> >> @interface ClassC
> >> -(ClassA*)someMethod:(ClassB*)b ;
> >> @end
> >> Doc for someMethod will contain only method declaration in plain text.
> >> Alternative, we can make ClassA and ClassB link to appropriate > documentation
> >> pages for this classes.
Nice work! With your patch, imo, the support for appledoc is starting to be very good (a testament of the flexibility of that tool). The links would be the cherry on the cake.
The only remaining issue that I know is that appledoc's markdown parser doesn't like github's Syntax highlighting and Fenced code blocks which are often used in the README files.
