More documentation for Exception class. #4420

akzhan · 2017-05-16T23:44:15Z

Heavily inspired by https://ruby-doc.org/core-2.4.0/Exception.html
[ci skip]

Heavily inspired by https://ruby-doc.org/core-2.4.0/Exception.html [ci skip]

ysbaddaden · 2017-05-17T07:22:59Z

Some notes:

Exception is missing an introductory header, you immediately talk about descendants, when the second line would fit (without describing what is contained);
don't document to_s;
could you keep docs around 80 chars, so they are easier to read in code?

RX14 · 2017-05-17T07:45:07Z

src/exception.cr

 class Exception
+  # Returns message of this exception.


I think this comment is rather useless without a description of what the message is used for.

RX14 · 2017-05-17T07:48:17Z

src/exception.cr

  def backtrace?
    @callstack.try &.printable_backtrace
  end

+  # Appends a `message` of this exception to the given *io*.


I do think that this to_s should be documented because often users want inspect_with_backtrace instead.

* Add introductory header to `Exception` class. * Add description for `DivisionByZero` class. * Drop documentation to *message* and *to_s*. * Other minor updates.

Sija · 2017-05-17T11:59:37Z

src/exception.cr

+# Represents errors that occur during application execution.
+#
+# Descendants of class Exception are used to communicate between raise and
+# rescue statements in begin ... end blocks.


begin ... end -> begin ... end

RX14 · 2017-05-17T12:16:31Z

src/exception.cr

@@ -2,18 +2,39 @@ require "callstack"

 CallStack.skip(__FILE__)

+# Represents errors that occur during application execution.
+#
+# Descendants of class Exception are used to communicate between raise and


How about "Exception and it's descendants are used ..."

Exception itself should not be used.

But it is used everywhere: https://github.com/crystal-lang/crystal/blob/master/src/raise.cr#L189.

Oops. OK :)

RX14 · 2017-05-17T12:19:03Z

src/exception.cr

+  # The backtrace is an array of strings, each containing
+  # “0xAddress: Function at File Line Column”.
+  #
+  # See also: `CallStack#decode_backtrace`.


CallStack is explicitly excluded from the docs so this "See also" probably won't help.

Thanks, removed.

RX14 · 2017-05-17T12:19:19Z

src/exception.cr

+  # The backtrace is an array of strings, each containing
+  # “0xAddress: Function at File Line Column”.
+  #
+  # See also: `CallStack#decode_backtrace`.


* begin ... end -> `begin ... end` * "Exception and it's descendants are used ..." * Don't mention about CallStack class that excluded from docs.

akzhan · 2017-05-17T14:34:26Z

Strange single build job failure (not related to the change).

RX14 · 2017-05-17T14:51:43Z

It looks like crystal's specs have an intermittent 32bit segfault in LLVM::Context#finalize. I think i've seen it before in another travis build.

akzhan · 2017-05-17T14:52:44Z

Reopened to retry the build.

akzhan · 2017-05-17T15:04:39Z

@RX14 looks like file sometimes isn't string. Fails here too:

      file, line, column = CallStack.decode_line_number(pc)
      if file == "??"

akzhan · 2017-05-17T16:16:22Z

Ditto

RX14 · 2017-05-17T16:22:07Z

If the build's failing due to unrelated reasons, just leave it and the core team will retry the build manually.

akzhan · 2017-05-17T16:25:14Z

Thanks for the information.

bcardiff · 2017-05-18T17:17:15Z

Thanks @akzhan !

More documentation for Exception class.

24e59e2

Heavily inspired by https://ruby-doc.org/core-2.4.0/Exception.html [ci skip]

RX14 requested changes May 17, 2017

View reviewed changes

Exception documentation updated:

d564fca

* Add introductory header to `Exception` class. * Add description for `DivisionByZero` class. * Drop documentation to *message* and *to_s*. * Other minor updates.

Sija reviewed May 17, 2017

View reviewed changes

RX14 requested changes May 17, 2017

View reviewed changes

Minor Exception class documentation update:

99a8e0b

* begin ... end -> `begin ... end` * "Exception and it's descendants are used ..." * Don't mention about CallStack class that excluded from docs.

akzhan closed this May 17, 2017

akzhan reopened this May 17, 2017

akzhan closed this May 17, 2017

akzhan reopened this May 17, 2017

bcardiff added the kind:docs label May 18, 2017

bcardiff added this to the Next milestone May 18, 2017

bcardiff merged commit 3c1678e into crystal-lang:master May 18, 2017

akzhan deleted the doc-Exception-class-more branch May 18, 2017 17:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

More documentation for Exception class. #4420

More documentation for Exception class. #4420

akzhan commented May 16, 2017

ysbaddaden commented May 17, 2017

RX14 May 17, 2017

RX14 May 17, 2017

Sija May 17, 2017

akzhan May 17, 2017

RX14 May 17, 2017

akzhan May 17, 2017

RX14 May 17, 2017

akzhan May 17, 2017

RX14 May 17, 2017

akzhan May 17, 2017

RX14 May 17, 2017

akzhan commented May 17, 2017

RX14 commented May 17, 2017 •

edited

akzhan commented May 17, 2017

akzhan commented May 17, 2017 •

edited

akzhan commented May 17, 2017

RX14 commented May 17, 2017

akzhan commented May 17, 2017

bcardiff commented May 18, 2017

More documentation for Exception class. #4420

More documentation for Exception class. #4420

Conversation

akzhan commented May 16, 2017

ysbaddaden commented May 17, 2017

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

akzhan commented May 17, 2017

RX14 commented May 17, 2017 • edited

akzhan commented May 17, 2017

akzhan commented May 17, 2017 • edited

akzhan commented May 17, 2017

RX14 commented May 17, 2017

akzhan commented May 17, 2017

bcardiff commented May 18, 2017

RX14 commented May 17, 2017 •

edited

akzhan commented May 17, 2017 •

edited