Documentation


(James Campbell) #1

Is there a way of improving the documentation and hosting it on Swift
instead of Apple ?

Currently the Array page lists all of the things the class directly
implements but doesn't include any of the methods mixed in by protocol
extensions (i.e all of the methods from CollectionType).

With YardDoc for Ruby it does this, so you know exactly what methods a
class has.

This confused me to no end as some topics here suggest adding ways of
dropping the first X elements and even I have implemented `shift` which I
didn't know already exist albeit under another name.

Would be great if we could improve these documents for the language in an
open source way :slight_smile:

ยทยทยท

--
๏ฃฟ Wizard
james@supmenow.com
+44 7523 279 698


(Ted Kremenek) #2

Hi James,

We're interested in hosting documentation on Swift.org for a variety of reasons. One motivating reason is to showcase the documentation for the version of the Standard Library that is in active development on 'master'. For example, whenever we generate a new snapshot that can be downloaded we update posted documentation.

We're exploring various options. If you have specific suggestions on what you would like to see, please speak up.

Thanks,
Ted

ยทยทยท

On Jan 6, 2016, at 11:06 AM, James Campbell via swift-dev <swift-dev@swift.org> wrote:

Is there a way of improving the documentation and hosting it on Swift instead of Apple ?

Currently the Array page lists all of the things the class directly implements but doesn't include any of the methods mixed in by protocol extensions (i.e all of the methods from CollectionType).

With YardDoc for Ruby it does this, so you know exactly what methods a class has.

This confused me to no end as some topics here suggest adding ways of dropping the first X elements and even I have implemented `shift` which I didn't know already exist albeit under another name.

Would be great if we could improve these documents for the language in an open source way :slight_smile:

--
๏ฃฟ Wizard
james@supmenow.com
+44 7523 279 698

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


(Trent Nadeau) #3

Reposting from thread on swift-evolution:

Big +1 from me. Rust's docs do this well too across trait implementations.
See, for example, https://doc.rust-lang.org/std/fs/struct.File.html.

ยทยทยท

On Wed, Jan 6, 2016 at 5:22 PM, Ted kremenek via swift-dev < swift-dev@swift.org> wrote:

Hi James,

We're interested in hosting documentation on Swift.org <http://swift.org>
for a variety of reasons. One motivating reason is to showcase the
documentation for the version of the Standard Library that is in active
development on 'master'. For example, whenever we generate a new snapshot
that can be downloaded we update posted documentation.

We're exploring various options. If you have specific suggestions on what
you would like to see, please speak up.

Thanks,
Ted

On Jan 6, 2016, at 11:06 AM, James Campbell via swift-dev < > swift-dev@swift.org> wrote:

Is there a way of improving the documentation and hosting it on Swift
instead of Apple ?

Currently the Array page lists all of the things the class directly
implements but doesn't include any of the methods mixed in by protocol
extensions (i.e all of the methods from CollectionType).

With YardDoc for Ruby it does this, so you know exactly what methods a
class has.

This confused me to no end as some topics here suggest adding ways of
dropping the first X elements and even I have implemented `shift` which I
didn't know already exist albeit under another name.

Would be great if we could improve these documents for the language in an
open source way :slight_smile:

--
๏ฃฟ Wizard
james@supmenow.com
+44 7523 279 698

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

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

--
Trent Nadeau


(James Campbell) #4

Someone shared this with me swiftdoc.org you guys should have a look at it,
its basically what I need.

ยทยทยท

On Wed, Jan 6, 2016 at 10:37 PM, Trent Nadeau <tanadeau@gmail.com> wrote:

Reposting from thread on swift-evolution:

Big +1 from me. Rust's docs do this well too across trait implementations.
See, for example, https://doc.rust-lang.org/std/fs/struct.File.html.

On Wed, Jan 6, 2016 at 5:22 PM, Ted kremenek via swift-dev < > swift-dev@swift.org> wrote:

Hi James,

We're interested in hosting documentation on Swift.org <http://swift.org>
for a variety of reasons. One motivating reason is to showcase the
documentation for the version of the Standard Library that is in active
development on 'master'. For example, whenever we generate a new snapshot
that can be downloaded we update posted documentation.

We're exploring various options. If you have specific suggestions on
what you would like to see, please speak up.

Thanks,
Ted

On Jan 6, 2016, at 11:06 AM, James Campbell via swift-dev < >> swift-dev@swift.org> wrote:

Is there a way of improving the documentation and hosting it on Swift
instead of Apple ?

Currently the Array page lists all of the things the class directly
implements but doesn't include any of the methods mixed in by protocol
extensions (i.e all of the methods from CollectionType).

With YardDoc for Ruby it does this, so you know exactly what methods a
class has.

This confused me to no end as some topics here suggest adding ways of
dropping the first X elements and even I have implemented `shift` which I
didn't know already exist albeit under another name.

Would be great if we could improve these documents for the language in an
open source way :slight_smile:

--
๏ฃฟ Wizard
james@supmenow.com
+44 7523 279 698

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

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

--
Trent Nadeau

--
๏ฃฟ Wizard
james@supmenow.com
+44 7523 279 698


(Erica Sadun) #5

These things are achievable, in my opinion. At a minimum, it's worth pinging Nate to have him join in on the discussion rather than trying to replace a really great site that already does a large part of what people are looking for.

-- Erica

ยทยทยท

On Jan 6, 2016, at 6:19 PM, Trent Nadeau via swift-dev <swift-dev@swift.org> wrote:

SwiftDoc is nice, but it doesn't quite do everything I want. The pages for protocols don't list implementing types in the stdlib, and the pages for types don't separate the methods by the protocol(s) that require them. Both are very useful when using generics so that the developer can create the best bounds (i.e., the ones that are least restrictive but still have the required operations and semantics).

On Wed, Jan 6, 2016 at 5:44 PM, James Campbell <james@supmenow.com <mailto:james@supmenow.com>> wrote:
swiftdoc.org <http://swiftdoc.org/>

--
Trent Nadeau
_______________________________________________
swift-dev mailing list
swift-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-dev


(Trent Nadeau) #6

SwiftDoc is nice, but it doesn't quite do everything I want. The pages for
protocols don't list implementing types in the stdlib, and the pages for
types don't separate the methods by the protocol(s) that require them. Both
are very useful when using generics so that the developer can create the
best bounds (i.e., the ones that are least restrictive but still have the
required operations and semantics).

ยทยทยท

On Wed, Jan 6, 2016 at 5:44 PM, James Campbell <james@supmenow.com> wrote:

swiftdoc.org

--
Trent Nadeau


(Trent Nadeau) #7

I completely agree. SwiftDoc is great, and I really appreciate Nate's work
in creating it. It's already very useful and is (IMHO) the prettiest
programming language docs site I've seen.

ยทยทยท

On Wed, Jan 6, 2016 at 9:52 PM, Erica Sadun <erica@ericasadun.com> wrote:

These things are achievable, in my opinion. At a minimum, it's worth
pinging Nate to have him join in on the discussion rather than trying to
replace a really great site that already does a large part of what people
are looking for.

-- Erica

On Jan 6, 2016, at 6:19 PM, Trent Nadeau via swift-dev < > swift-dev@swift.org> wrote:

SwiftDoc is nice, but it doesn't quite do everything I want. The pages for
protocols don't list implementing types in the stdlib, and the pages for
types don't separate the methods by the protocol(s) that require them. Both
are very useful when using generics so that the developer can create the
best bounds (i.e., the ones that are least restrictive but still have the
required operations and semantics).

On Wed, Jan 6, 2016 at 5:44 PM, James Campbell <james@supmenow.com> wrote:

swiftdoc.org

--
Trent Nadeau
_______________________________________________
swift-dev mailing list
swift-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-dev

--
Trent Nadeau


(Nate Cook) #8

Thanks, Erica!

Trent, swiftdoc.org <http://swiftdoc.org/> doesn't list the implementing types, but you can see them graphically if you click on the "View Protocol Hierarchy" button on any type or protocol page. Separating the methods by the requiring protocols is a bit trickier, but probably achievable. In any case, it's great to hear constructive feedback from people who've seen the site -- please feel free to open an issue with comments/requests/suggestions:
ย ย https://github.com/SwiftDocOrg/swiftdoc.org

Nate

ยทยทยท

On Jan 6, 2016, at 8:52 PM, Erica Sadun <erica@ericasadun.com> wrote:

These things are achievable, in my opinion. At a minimum, it's worth pinging Nate to have him join in on the discussion rather than trying to replace a really great site that already does a large part of what people are looking for.

-- Erica

On Jan 6, 2016, at 6:19 PM, Trent Nadeau via swift-dev <swift-dev@swift.org <mailto:swift-dev@swift.org>> wrote:

SwiftDoc is nice, but it doesn't quite do everything I want. The pages for protocols don't list implementing types in the stdlib, and the pages for types don't separate the methods by the protocol(s) that require them. Both are very useful when using generics so that the developer can create the best bounds (i.e., the ones that are least restrictive but still have the required operations and semantics).

On Wed, Jan 6, 2016 at 5:44 PM, James Campbell <james@supmenow.com <mailto:james@supmenow.com>> wrote:
swiftdoc.org <http://swiftdoc.org/>

--
Trent Nadeau
_______________________________________________
swift-dev mailing list
swift-dev@swift.org <mailto:swift-dev@swift.org>
https://lists.swift.org/mailman/listinfo/swift-dev


(James Campbell) #9

Wasn't looking to replace but assist by maybe linking to it and even maybe bringing his repos under the official repo And Nate could still be a contributor

ยทยทยท

Sent from my iPhone

On 7 Jan 2016, at 05:33, Trent Nadeau <tanadeau@gmail.com> wrote:

I completely agree. SwiftDoc is great, and I really appreciate Nate's work in creating it. It's already very useful and is (IMHO) the prettiest programming language docs site I've seen.

On Wed, Jan 6, 2016 at 9:52 PM, Erica Sadun <erica@ericasadun.com> wrote:
These things are achievable, in my opinion. At a minimum, it's worth pinging Nate to have him join in on the discussion rather than trying to replace a really great site that already does a large part of what people are looking for.

-- Erica

On Jan 6, 2016, at 6:19 PM, Trent Nadeau via swift-dev <swift-dev@swift.org> wrote:

SwiftDoc is nice, but it doesn't quite do everything I want. The pages for protocols don't list implementing types in the stdlib, and the pages for types don't separate the methods by the protocol(s) that require them. Both are very useful when using generics so that the developer can create the best bounds (i.e., the ones that are least restrictive but still have the required operations and semantics).

On Wed, Jan 6, 2016 at 5:44 PM, James Campbell <james@supmenow.com> wrote:

swiftdoc.org

--
Trent Nadeau
_______________________________________________
swift-dev mailing list
swift-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-dev

--
Trent Nadeau