Documentation and coding style


(Sergej Jaskiewicz) #1

Hello everyone.

I have a couple of questions about the core libraries that I think would be interesting to discuss.

The first question is about documentation comments. From what I can see in the repos and what the core team members say, those libraries lack them a lot. Maybe some of you have already asked this question, but can’t we just copy the Darwin Foundation & XCTest documentation comments? I can see it has been done in some parts of Swift Foundation, so why don’t we apply it to all the APIs? Of course taking into account the possible differences in behaviour or implementation.

The second question is about a coding style. It can be seen that in different parts of the Foundation/XCTest the coding style quite often differs. Maybe we could develop some kind of a document that would state the general rules.

Do you have any thoughts on this?

— Sergej


(Tony Parker) #2

Hi Sergej,

Hello everyone.

I have a couple of questions about the core libraries that I think would be interesting to discuss.

The first question is about documentation comments. From what I can see in the repos and what the core team members say, those libraries lack them a lot. Maybe some of you have already asked this question, but can’t we just copy the Darwin Foundation & XCTest documentation comments? I can see it has been done in some parts of Swift Foundation, so why don’t we apply it to all the APIs? Of course taking into account the possible differences in behaviour or implementation.

I would be happy to accept PRs that add documentation to the existing API. There was just too much of it for us to finish in the first sweep of importing API into the project.

The second question is about a coding style. It can be seen that in different parts of the Foundation/XCTest the coding style quite often differs. Maybe we could develop some kind of a document that would state the general rules.

This is a sure fire way to start a controversy. =)

I’m in a bit of wait-and-see on this. For example, I’m personally 100% opposed to hard wrapping at 80 chars - but that’s the style used in the standard library. Perhaps a more consistent style will evolve over time.

- Tony

···

On Jan 20, 2017, at 6:24 AM, Sergej Jaskiewicz via swift-corelibs-dev <swift-corelibs-dev@swift.org> wrote:

Do you have any thoughts on this?

— Sergej
_______________________________________________
swift-corelibs-dev mailing list
swift-corelibs-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-corelibs-dev