D13571: Correct KFormat::formatBytes examples

[Stefan Brüns]

This revision was automatically updated to reflect the committed changes.
Closed by commit R244:59dc873bcbe1: Correct KFormat::formatBytes examples 
(authored by bruns).

REPOSITORY
  R244 KCoreAddons

CHANGES SINCE LAST UPDATE
  https://phabricator.kde.org/D13571?vs=36731=37744

REVISION DETAIL
  https://phabricator.kde.org/D13571

AFFECTED FILES
  autotests/kformattest.cpp
  src/lib/util/kformat.h

To: bruns, #frameworks, dhaumann
Cc: dhaumann, apol, kde-frameworks-devel, michaelh, ngraham, bruns

D13571: Correct KFormat::formatBytes examples

[Dominik Haumann]

dhaumann accepted this revision.
dhaumann added a comment.
This revision is now accepted and ready to land.


  I think this is an improvement. Even if it can be improved even more, I 
believe it is better to push this instead of postponing a commit.

REPOSITORY
  R244 KCoreAddons

BRANCH
  kformat_doc

REVISION DETAIL
  https://phabricator.kde.org/D13571

To: bruns, #frameworks, dhaumann
Cc: dhaumann, apol, kde-frameworks-devel, michaelh, ngraham, bruns

D13571: Correct KFormat::formatBytes examples

[Stefan Brüns]

bruns marked 2 inline comments as done.
bruns added a comment.


  ping!

REPOSITORY
  R244 KCoreAddons

REVISION DETAIL
  https://phabricator.kde.org/D13571

To: bruns, #frameworks
Cc: apol, kde-frameworks-devel, michaelh, ngraham, bruns

D13571: Correct KFormat::formatBytes examples

[Stefan Brüns]

bruns updated this revision to Diff 36731.
bruns added a comment.


  Use @code/@endcode
  Reword extended documentation for precision parameter

REPOSITORY
  R244 KCoreAddons

CHANGES SINCE LAST UPDATE
  https://phabricator.kde.org/D13571?vs=36234=36731

BRANCH
  kformat_doc

REVISION DETAIL
  https://phabricator.kde.org/D13571

AFFECTED FILES
  autotests/kformattest.cpp
  src/lib/util/kformat.h

To: bruns, #frameworks
Cc: apol, kde-frameworks-devel, michaelh, ngraham, bruns

D13571: Correct KFormat::formatBytes examples

[Stefan Brüns]

bruns added a comment.


  In D13571#280135 , @apol wrote:
  
  > In D13571#279554 , @bruns wrote:
  >
  > > In D13571#279550 , @apol wrote:
  > >
  > > > > The given example is just plain wrong. It does not work, it is just 
some false prosa.
  > > >
  > > > Fair enough, yet the API user may want to be able to understand what's 
the logic behind it, so if it can be explained on the documentation that could 
be useful.
  > >
  > >
  > > What is "it"?
  > >
  > > This patch does not change any behaviour, it just ensures the 
documentation matches reality.
  >
  >
  > Don't make me read the code. You are updating documentation, the 
documentation itself needs to offer such information.
  
  
  I was referring to you vague formulation "understand what's the logic behind 
it". Apparently you need some clarification for "something". Why don't you tell 
what "something" is?
  
  Instead of accepting a documentation *fix*, you are nitpicking about 
something, but you do not really tell what you don't like.
  
  The example code neither compiles, nor does the output - after fixing the 
broken code - match the output from the documentation.

REPOSITORY
  R244 KCoreAddons

REVISION DETAIL
  https://phabricator.kde.org/D13571

To: bruns, #frameworks
Cc: apol, kde-frameworks-devel, michaelh, ngraham, bruns

D13571: Correct KFormat::formatBytes examples

[Aleix Pol Gonzalez]

apol added a comment.


  In D13571#279554 , @bruns wrote:
  
  > In D13571#279550 , @apol wrote:
  >
  > > > The given example is just plain wrong. It does not work, it is just 
some false prosa.
  > >
  > > Fair enough, yet the API user may want to be able to understand what's 
the logic behind it, so if it can be explained on the documentation that could 
be useful.
  >
  >
  > What is "it"?
  >
  > This patch does not change any behaviour, it just ensures the documentation 
matches reality.
  
  
  Don't make me read the code. You are updating documentation, the 
documentation itself needs to offer such information.

REPOSITORY
  R244 KCoreAddons

REVISION DETAIL
  https://phabricator.kde.org/D13571

To: bruns, #frameworks
Cc: apol, kde-frameworks-devel, michaelh, ngraham, bruns

D13571: Correct KFormat::formatBytes examples

[Stefan Brüns]

bruns added inline comments.

INLINE COMMENTS

> kformattest.cpp:37
>  QCOMPARE(format.formatByteSize(0), QStringLiteral("0 B"));
>  QCOMPARE(format.formatByteSize(50), QStringLiteral("50 B"));
>  QCOMPARE(format.formatByteSize(500), QStringLiteral("500 B"));

See here for handling of precision for small values. Or read the code in 
kformatprivate.cpp.

REPOSITORY
  R244 KCoreAddons

REVISION DETAIL
  https://phabricator.kde.org/D13571

To: bruns, #frameworks
Cc: apol, kde-frameworks-devel, michaelh, ngraham, bruns

D13571: Correct KFormat::formatBytes examples

[Stefan Brüns]

bruns added a comment.


  In D13571#279550 , @apol wrote:
  
  > > The given example is just plain wrong. It does not work, it is just some 
false prosa.
  >
  > Fair enough, yet the API user may want to be able to understand what's the 
logic behind it, so if it can be explained on the documentation that could be 
useful.
  
  
  What is "it"?
  
  This patch does not change any behaviour, it just ensures the documentation 
matches reality.

REPOSITORY
  R244 KCoreAddons

REVISION DETAIL
  https://phabricator.kde.org/D13571

To: bruns, #frameworks
Cc: apol, kde-frameworks-devel, michaelh, ngraham, bruns

D13571: Correct KFormat::formatBytes examples

[Aleix Pol Gonzalez]

apol added a comment.


  > The given example is just plain wrong. It does not work, it is just some 
false prosa.
  
  Fair enough, yet the API user may want to be able to understand what's the 
logic behind it, so if it can be explained on the documentation that could be 
useful.

INLINE COMMENTS

> bruns wrote in kformat.h:184
> respectively

Please use the full word.

REPOSITORY
  R244 KCoreAddons

REVISION DETAIL
  https://phabricator.kde.org/D13571

To: bruns, #frameworks
Cc: apol, kde-frameworks-devel, michaelh, ngraham, bruns

D13571: Correct KFormat::formatBytes examples

[Stefan Brüns]

bruns marked an inline comment as done.
bruns added a comment.


  In D13571#279453 , @apol wrote:
  
  > Then explain why it works? Actually the former behaviour is what I'd expect.
  
  
  The given example is just plain wrong. It does not work, it is just some 
false prosa.

REPOSITORY
  R244 KCoreAddons

REVISION DETAIL
  https://phabricator.kde.org/D13571

To: bruns, #frameworks
Cc: apol, kde-frameworks-devel, michaelh, ngraham, bruns

D13571: Correct KFormat::formatBytes examples

[Stefan Brüns]

bruns marked an inline comment as done.
bruns added inline comments.

INLINE COMMENTS

> apol wrote in kformat.h:184
> What's "resp."?

respectively

REPOSITORY
  R244 KCoreAddons

REVISION DETAIL
  https://phabricator.kde.org/D13571

To: bruns, #frameworks
Cc: apol, kde-frameworks-devel, michaelh, ngraham, bruns

D13571: Correct KFormat::formatBytes examples

[Aleix Pol Gonzalez]

apol added a comment.


  Then explain why it works? Actually the former behaviour is what I'd expect.

INLINE COMMENTS

> kformat.h:184
> + *1 by default so when in doubt use 1. Integral values less than 
> 1000
> + *resp. 1024 always omit the fractional part.
>   * @param dialect binary unit standard to use.  Use DefaultBinaryDialect 
> to

What's "resp."?

REPOSITORY
  R244 KCoreAddons

REVISION DETAIL
  https://phabricator.kde.org/D13571

To: bruns, #frameworks
Cc: apol, kde-frameworks-devel, michaelh, ngraham, bruns

D13571: Correct KFormat::formatBytes examples

[Stefan Brüns]

bruns created this revision.
bruns added a reviewer: Frameworks.
Restricted Application added a project: Frameworks.
Restricted Application added a subscriber: kde-frameworks-devel.
bruns requested review of this revision.

REVISION SUMMARY
  The example left out the "precision" parameter, reported values where
  wrong (values are rounded, not truncated). The precision parameter is
  ignored for values less than 1000 resp. 1024.

TEST PLAN
  make test

REPOSITORY
  R244 KCoreAddons

BRANCH
  master

REVISION DETAIL
  https://phabricator.kde.org/D13571

AFFECTED FILES
  autotests/kformattest.cpp
  src/lib/util/kformat.h

To: bruns, #frameworks
Cc: kde-frameworks-devel, michaelh, ngraham, bruns