ponyc
ponyc copied to clipboard
ponylang
Write class String documentation
There's some method level documentation but the class level where we should have lots of example code etc is just:
Strings don't specify an encoding
Still need to add examples showing how encoding works, how accessing characters works
Not entirely happy with substring behaviour.
Filed #1088
Given the importance of string, I think we could add still more to bring ourselves up to having basics. I'm quite open to convincing.
I'm touching on this in the string api RFC, but I actually think it would be worthwhile having a chapter in the tutorial on the builtin types that includes common use-cases. Out of scope for this ticket perhaps, as this relates to the class-level documentation.
I'm not sure the tutorial is the right place for that. A "guide to the standard library" does sound like a good idea. I would imagine it to be a more guided version of what you get from the standard library docs. Perhaps it is the standard library docs but with meta information guiding you through it.
To be clear, I am only talking about types in the builtin package, or at least those with literal syntax. A guide to the standard library sounds nice, though perhaps a cookbook would be an alternative way to illustrate "how to use". Not sure there is an obvious linear narrative for the library, but maybe just a collection of fundamentals - i/o, file access, networking etc.
From a user standpoint, there's no difference between the classes in the builtin package vs those outside of it. Builtin exists because they require compiler support. There's no other reason for their organization into that package, so I wouldn't use that as a delimiting line for any documentation.
Commenting so this get reviewed during Sync eventually.
There are a handful of methods without docstrings, but I do not think it is clear from the current state of String documentation and the thread here what is left to do before closing this issue.
