On Nov 22, 2014, at 1:27 AM, Richard Charles <rcharles...@gmail.com> wrote:
> Perhaps it is just me, but it is not uncommon for my source file to have many
> more methods than what is in my header. So for me it is not the replicated
> code in the header file that is a negative but rather it is being forced to
> define the interface that ends up being a positive.
>
> My documentation style is patterned after Richard Hipp’s SQLite project where
> a detailed description of each interface routine is found in the source code.
> A quick glance at the header file gives you an overview of the interface. If
> you need more information then go to the source code.
>
> Overall this results in smaller header files and a more readily comprehended
> interface. I find this very beneficial when working with a large project, it
> help me keep my sanity.
There’s another approach. I resist it, but I suspect the resistance comes
mostly of my not being used to it.
Swift extensions are not like Objective-C categories. They’re cheap; they have
first-class access to the class’s internals. (Not privates, I hope.) Put your
public interface in the main class file, and the private workings in the
extension. You still have to expose your source, but at least you can restrict
it to public API.
I respect your concern about summary vs. detailed documentation. My solution is
surrender: I have Ruby scripts and C-family headers that are 80% documentation,
because I think of them as source for a consolidated reference, not a quick
lookup. I was happy enough with the summaries extracted by aggregators like
Doxygen, for which there is no replacement, and I’m glum about there being one
any time soon.
How dismal is the current situation with reStructuredText is off the topic of
this thread, so I’ll restrain myself.
— F
_______________________________________________
Cocoa-dev mailing list (Cocoa-dev@lists.apple.com)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com
This email sent to arch...@mail-archive.com
