-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
added documentation for Kernel#sprintf method (fixes #3124) #5762
added documentation for Kernel#sprintf method (fixes #3124) #5762
Conversation
* Fix docs directory in gitignore.ecr (renamed in #4937)
Debug::DWARF::LineNumbers would skip the program statement when it contained a single entry, because of a wrong assumption of the sequence unit_length entry, which doesn't account for the unit length space in the standard, and was overlooked in checking whether the sequence had any program statement, or not.
…L::Context::Server Fixes #5266 x509 certificates have a purpose associated to them. Clients should verify that the server's certificate is intended to be used in a server, and servers should check the client's certificate is intended to be used for clients. Crystal was mistakingly checking those mixed up. See https://wiki.openssl.org/index.php?title=Manual:X509(1)&oldid=1797#CERTIFICATE_EXTENSIONS See https://tools.ietf.org/html/rfc5280#section-4.2.1.3
Move setup from .travis.yml to /bin/ci
Build master, release and ci branches Build tags
Make travis build ci branches
* Colorize: abstract colors and support 8bit and true color Closes #5900 * Color#fore and #back take io to avoid memory allocation * Use character literal instead of 1 length string
src/io.cr
Outdated
@@ -281,6 +281,8 @@ abstract class IO | |||
nil | |||
end | |||
|
|||
# Writes a formatted string to this IO. | |||
# For details on the format string, see `Kernel::sprintf` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
period is missing.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Kernel::sprintf
won't produce a link, use ::sprintf
instead.
src/kernel.cr
Outdated
@@ -57,7 +57,7 @@ end | |||
|
|||
# Prints a formatted string to `STDOUT`. | |||
# | |||
# See also: `IO#printf`. | |||
# For details on the format string, see `sprintf` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
period is missing.
src/kernel.cr
Outdated
# Returns a formatted string. | ||
# Returns the string resulting from applying `format_string` to | ||
# any additional arguments. | ||
# Within the format string, any characters other than format sequences |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
*format_string*
src/kernel.cr
Outdated
@@ -67,9 +67,227 @@ def printf(format_string, args : Array | Tuple) : Nil | |||
STDOUT.printf format_string, args | |||
end | |||
|
|||
# Returns a formatted string. | |||
# Returns the string resulting from applying `format_string` to | |||
# any additional arguments. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This sounds weird: format_string
is not applied to the additional arguments. I'd keep the first sentence really simple and add details later:
Returns a formatted string.
The string is produced according to the *format_string* with format specifiers being replaced
by values from *args* formatted according to the specifier.
src/kernel.cr
Outdated
# | ||
# See also: `IO#printf`. | ||
# The syntax for a format sequence is: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd rather call it format specifier like the C docs. Ditto all further references.
src/kernel.cr
Outdated
# A format sequence consists of a percent sign, followed by optional flags, | ||
# width, and precision indicators, then terminated with a field type | ||
# character. The field type controls how the corresponding | ||
# <code>sprintf</code> argument is to be interpreted, while the flags |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
<code>
tags probably won't work with markdown renderer (haven't tried it, though).
src/kernel.cr
Outdated
# | ||
# The field type characters are: | ||
# | ||
# Field | Integer Format |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This will just produce clutter. I don't think there is a way to use a table in API docs. This needs to be improved (see #4613).
For now, these tables should be wrapped in plain code fences to use <pre>
tag for formatting.
src/kernel.cr
Outdated
# | ||
# Field | Integer Format | ||
# ------+-------------------------------------------------------------- | ||
# b | Convert argument as a binary number. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Formats argument as...
would be better. Ditto for following lines.
src/kernel.cr
Outdated
# d | Convert argument as a decimal number. | ||
# i | Same as `d`. | ||
# o | Convert argument as an octal number. | ||
# x | Convert argument as a hexadecimal number. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
please add using lowercase letters
.
src/kernel.cr
Outdated
# ------+-------------------------------------------------------------- | ||
# c | Argument is the numeric code for a single character or | ||
# | a single character string itself. | ||
# p | The value of argument.inspect. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This specifier doesn't seem to be implemented.
You should check the resulting HTML output produced by your API docs. |
* Pass an unhandled exception to at_exit block as second argument Follow up #1921 It is better in some ways: - it does not need a new exception like `SystemExit`. - it does not break compatibility in most cases because block fill up lacking arguments. * Add documentation for at_exit block arguments * Update `at_exit` block arguments description #5906 (comment) Thank you @jhass.
@straight-shoota added the fixes as suggested.
|
Run |
oh, that did work! |
@straight-shoota table is looking good now. |
src/kernel.cr
Outdated
# The string is produced according to the *format_string* with format specifiers | ||
# being replaced by values from *args* formatted according to the specifier. | ||
# Within the format string, any characters other than format specifiers | ||
# (specifiers beginning with %) are copied to the result. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
`%`
Looks good! You should rebase on |
…m:CaDs/crystal into fix/added_documentation_for_printf_method
damn I messed up the rebase, closing this PR |
Issue: #3124
As suggested per @asterite on this previous PR I have used Ruby's sprintf documentation as a template.
The previous examples are using this pattern
but I think that adding all those steps for all the examples I wrote would be just too much.
If you have a better approach, please let me know.
As a side note I would like to mention that, while I was working on the different samples, I noticed that the
#
option is being processed but actually never used so I wrote a question mark there.