added documentation for Kernel#sprintf method (fixes #3124) #5762

CaDs · 2018-03-03T04:08:59Z

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

io = IO::Memory.new
io.puts "hello\n"
io.puts "world"
io.to_s # => "hello\nworld\n"

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.

* 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.

@asterite

* Add ASTNode#single_expression and refactor with using it Fixed #5482 Fixed #5511 But this commit contains no spec for #5511 because I don't know where to place such a spec. * Add spec for #5511 Thank you @asterite! See: #5513 (comment)

…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

#5892 (comment)

* 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

straight-shoota · 2018-04-03T12:47:44Z

src/io.cr

@@ -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`


period is missing.

Kernel::sprintf won't produce a link, use ::sprintf instead.

straight-shoota · 2018-04-03T12:47:54Z

src/kernel.cr

@@ -57,7 +57,7 @@ end

 # Prints a formatted string to `STDOUT`.
 #
-# See also: `IO#printf`.
+# For details on the format string, see `sprintf`


period is missing.

straight-shoota · 2018-04-03T12:58:12Z

src/kernel.cr

-# 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


*format_string*

straight-shoota · 2018-04-03T12:58:13Z

src/kernel.cr

@@ -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.


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.

straight-shoota · 2018-04-03T12:58:52Z

src/kernel.cr

 #
-# See also: `IO#printf`.
+# The syntax for a format sequence is:


I'd rather call it format specifier like the C docs. Ditto all further references.

straight-shoota · 2018-04-03T13:01:32Z

src/kernel.cr

+# 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


<code> tags probably won't work with markdown renderer (haven't tried it, though).

straight-shoota · 2018-04-03T13:05:33Z

src/kernel.cr

+#
+# The field type characters are:
+#
+#     Field |  Integer Format


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.

straight-shoota · 2018-04-03T13:15:52Z

src/kernel.cr

+#
+#     Field |  Integer Format
+#     ------+--------------------------------------------------------------
+#       b   | Convert argument as a binary number.


Formats argument as... would be better. Ditto for following lines.

straight-shoota · 2018-04-03T13:16:57Z

src/kernel.cr

+#       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.


please add using lowercase letters.

straight-shoota · 2018-04-03T13:21:45Z

src/kernel.cr

+#     ------+--------------------------------------------------------------
+#       c   | Argument is the numeric code for a single character or
+#           | a single character string itself.
+#       p   | The value of argument.inspect.


This specifier doesn't seem to be implemented.

straight-shoota · 2018-04-03T13:23:54Z

You should check the resulting HTML output produced by your API docs.

@jhass

* 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.

* Fix #5907 formatter bug * Apply new formatter

CaDs · 2018-04-03T23:51:15Z

@straight-shoota added the fixes as suggested.
As for checking the resulting HTML I'm trying to do that but each time I run crystal docs command I'm getting an error

Error in line 1: while requiring "./src/**"

in src/base64.cr:23: already initialized constant Base64::CHARS_STD

  private CHARS_STD  = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"

straight-shoota · 2018-04-03T23:52:52Z

Run make docs to generate the stdlib API docs.

CaDs · 2018-04-03T23:53:47Z

oh, that did work!
thanks

CaDs · 2018-04-04T00:03:50Z

@straight-shoota table is looking good now.
Thanks for the suggestion 🙇

straight-shoota · 2018-04-04T08:26:31Z

src/kernel.cr

+# 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.


straight-shoota · 2018-04-04T08:29:37Z

Looks good!

You should rebase on master to get green CI. It's only doc changes, but still...

…rmat fixed

…escription

…m:CaDs/crystal into fix/added_documentation_for_printf_method

CaDs · 2018-04-04T08:52:16Z

damn I messed up the rebase, closing this PR

cotsog and others added 30 commits December 26, 2017 14:47

Enable IPv6 in Docker (#5429)

68c0098

Update bin/ci to use LIBRARY_PATH from 0.24.1 (#5461)

4313e86

Fix missing Dir#each to be an Enumerable (#5458)

12cc7f2

Update gitignore template (#5480)

4f56a57

* Fix docs directory in gitignore.ecr (renamed in #4937)

Rename skip() macro method to skip_file() in docs (#5488)

d3fed8b

Include UUID in docs

e1680dd

Fix formatting of lib's fun starting with uppercase letter

b793876

Add formatter spec for uppercased fun call

7f05801

Version 0.24.2

1445529

Migrate to Circle 2.0

8e621ad

Set TZ for osx builds

6418ee4

Enable ipv6 for docker in linux build

6b655af

Move setup from .travis.yml to /bin/ci

Add linux builds for 64 and 32 bits

d08d7c9

Add branch and tag filter to ci

1a1124b

Build master, release and ci branches Build tags

Test nightly build

9538efb

Check if circle can handle release optimized builds

5c06ff9

Add darwin nightly artifacts

bfc9f79

Collect dist packages of jobs as artifacts

85d895f

Add docs as nightly artifacts

ccdf9c1

Remove docs publishing from travis

a4ed534

Make travis build ci branches

Add docker image as nightly artifact

d5e952f

Split build/publish docker targets. Build docs from docker image.

80a1c4a

DRY checkout of distribution-scripts. Use docker executor where possible

e3c3f7f

Parametrise previous crystal release, package iteration and docker

66600d6

Shorten jobs names

19981d3

Update paths from distribution-scripts

4cf8a7c

added documentation for IO#printf method

40fbca0

makenowjust and others added 3 commits April 3, 2018 00:42

Format: fix indentation after backslash newline (#5901)

60f675c

#5892 (comment)

Use LibCrystalMain.__crystal_main directly (#5899)

7eae5aa

Colorize: abstract colors and support 8bit and true color (#5902)

bb5bcd2

* 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

straight-shoota requested changes Apr 3, 2018

View reviewed changes

makenowjust and others added 4 commits April 3, 2018 15:18

Semantic: don't guess ivar type from argument after assigned (#5166)

82caaf0

Fix #5907 formatter bug (#5909)

ec423eb

* Fix #5907 formatter bug * Apply new formatter

feedback added

7998380

fixed display for table

2e966f0

straight-shoota reviewed Apr 4, 2018

View reviewed changes

CaDs and others added 10 commits April 4, 2018 17:43

added documentation for IO#printf method

bd11f12

added fixes upon feedback

a149922

moved documentation from IO#print to Kernel#sprintf upon feedback. Fo…

9ff5f8b

…rmat fixed

added fixes upon feedback

074efa1

fixed overzealous dittoing

7db56c2

wrapping the samples in blocks and giving each sample block a valid d…

efe973c

…escription

feedback added

78bb324

fixed display for table

68b8351

Merge branch 'fix/added_documentation_for_printf_method' of github.co…

96a950a

…m:CaDs/crystal into fix/added_documentation_for_printf_method

rebased, added feedback

3c3b4bd

CaDs closed this Apr 4, 2018

CaDs deleted the fix/added_documentation_for_printf_method branch April 4, 2018 08:47

CaDs restored the fix/added_documentation_for_printf_method branch April 4, 2018 08:49

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

added documentation for Kernel#sprintf method (fixes #3124) #5762

added documentation for Kernel#sprintf method (fixes #3124) #5762

CaDs commented Mar 3, 2018

straight-shoota Apr 3, 2018

straight-shoota Apr 3, 2018

straight-shoota Apr 3, 2018

straight-shoota Apr 3, 2018

straight-shoota Apr 3, 2018

straight-shoota Apr 3, 2018

straight-shoota Apr 3, 2018

straight-shoota Apr 3, 2018

straight-shoota Apr 3, 2018

straight-shoota Apr 3, 2018

straight-shoota Apr 3, 2018

straight-shoota commented Apr 3, 2018

CaDs commented Apr 3, 2018

straight-shoota commented Apr 3, 2018

CaDs commented Apr 3, 2018

CaDs commented Apr 4, 2018

straight-shoota Apr 4, 2018

straight-shoota commented Apr 4, 2018

CaDs commented Apr 4, 2018

added documentation for Kernel#sprintf method (fixes #3124) #5762

added documentation for Kernel#sprintf method (fixes #3124) #5762

Conversation

CaDs commented Mar 3, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

straight-shoota commented Apr 3, 2018

CaDs commented Apr 3, 2018

straight-shoota commented Apr 3, 2018

CaDs commented Apr 3, 2018

CaDs commented Apr 4, 2018

Choose a reason for hiding this comment

straight-shoota commented Apr 4, 2018

CaDs commented Apr 4, 2018