appledoc improvements

Showing 1-10 of 10 messages
appledoc improvements Eloy Durán 4/12/12 3:15 AM
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.

Cheers,
Eloy

[1] http://gentlebytes.com/appledoc/ & https://github.com/tomaz/appledoc
[2] http://twitpic.com/98svq5
[3] http://twitpic.com/98svyr

Re: appledoc improvements SevInf 4/12/12 4:00 AM
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 написал:
Re: appledoc improvements Eloy Durán 4/12/12 4:12 AM
Awesome, Sergej. Thanks!
Re: appledoc improvements SevInf 4/12/12 7:47 AM
First try - https://github.com/SevInf/appledoc/commit/2bb54d56463fa74f68654af4eb24d8e96054971e.
After this change method prototype with types info will be visible even without doc comments(screenshot http://habrastorage.org/storage2/c0f/c23/74c/c0fc2374c7f774847eeefd62c4e6c389.png).
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.


четверг, 12 апреля 2012 г., 13:15:34 UTC+3 пользователь Eloy Durán написал:
Hey guys,
Re: appledoc improvements Eloy Durán 4/12/12 2:54 PM
Wow, that was fast!

> First try - https://github.com/SevInf/appledoc/commit/2bb54d56463fa74f68654af4eb24d8e96054971e.
> After this change method prototype with types info will be visible even without doc comments(screenshot http://habrastorage.org/storage2/c0f/c23/74c/c0fc2374c7f774847eeefd62c4e6c389.png).

Looks excellent.

> 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?

Re: appledoc improvements SevInf 4/13/12 1:20 AM

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. 
Re: appledoc improvements Eloy Duran 4/13/12 1:35 AM
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:

http://pspdfkit.com/documentation/Classes/PSPDFPageView.html#//api/name/displayDocument:page:pageRect:scale:delayPageAnnotations:pdfController:

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?

Re: appledoc improvements Eloy Duran 4/13/12 3:32 AM
Btw, just installed your fork and re-generated my docs; it’s sooo much
better now :)
Re: appledoc improvements SevInf 4/13/12 4:17 AM
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 написал:
Re: appledoc improvements Fabio Pelosin 4/14/12 10:03 AM
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.