Improve docs

[msooseth]

Description

An attempt at improving the documentation. I decided to remove the overly long (and usually out-of-date) list of options, and keep only the most important in the doc. I also refer the user to the full list via the appropriate --help call each time.

I have specifically added a section on equivalence, in particular, about what is being compared, and how the --create flag works.

Related to #688

Checklist

• tested locally
• added automated tests
• updated the docs
• updated the changelog

[konnov]

Thanks a lot for improving the documentation. The explanation of what constitutes equivalence definitely helps! It would be also great, if --help had a pointer to the documentation. It would remind people like me, who are trying to check something in a rush, to check the docs.

[msooseth]

Ah, that's actually a good point. Let me add that :)

[msooseth]

Hahaha I can't... Options.Command is not made for human consumption. I can add it, but only to the main --help, not the sub-help of e.g. symbolic, and it also removes the detailed help... weird.

[msooseth]

Thanks a lot for improving the documentation. The explanation of what constitutes equivalence definitely helps! It would be also great, if --help had a pointer to the documentation. It would remind people like me, who are trying to check something in a rush, to check the docs.

That's actually a great idea, and I have tried adding that line and it's been 3h of struggling with Options. We use Options in a rather special way. And that doesn't seem to allow that. I think I will have to rewrite our cli.hs and then it will work. For the moment, I'll leave it as-is and will create a new PR to add that help line at the bottom :)

[blishko]

Nice! Just left a few questions.

[blishko]

Should we call this option --max-calldata-buf-size?

[msooseth]

Good point! Yes, we should. Fixing.

[msooseth]

Ah wait... this actually applies to other buffers too, like here:

symCalldata :: App m => Text -> [AbiType] -> [String] -> Expr Buf -> m (Expr Buf, [Prop])
symCalldata sig typesignature concreteArgs base = do
  conf <- readConfig
  let
    args = concreteArgs <> replicate (length typesignature - length concreteArgs) "<symbolic>"
    mkArg :: AbiType -> String -> Int -> CalldataFragment
    mkArg typ "<symbolic>" n = symAbiArg (T.pack $ "arg" <> show n) typ
    mkArg typ arg _ =
      case makeAbiValue typ arg of
        AbiUInt _ w -> St [] . Lit . into $ w
        AbiInt _ w -> St [] . Lit . unsafeInto $ w
        AbiAddress w -> St [] . Lit . into $ w
        AbiBool w -> St [] . Lit $ if w then 1 else 0
        _ -> internalError "TODO"
    calldatas = zipWith3 mkArg typesignature args [1..]
    (cdBuf, props) = combineFragments calldatas base
    withSelector = writeSelector cdBuf sig
    sizeConstraints
      = (Expr.bufLength withSelector .>= cdLen calldatas)
      .&& (Expr.bufLength withSelector .< (Lit (2 ^ conf.maxBufSize)))

and also the data that an unknown contract sends back to us. We should explain this...

[msooseth]

OK, I am gonna talk about this more in the docs and try to give a better explanation in the --help, too.

[blishko]

What does ... mean here?

[msooseth]

I was trying to imply that there are more options... maybe I should remove? I don't want to list them all, I think it's not that useful? What do you think?

[blishko]

Why not document all the options?
It seems unusual to omit some of them.
Unless you can argue they belong to separate categories, like "for users" and "for developers"?
And you want to list only those important for the users.

[msooseth]

Well, we keep adding some and then not documenting them in the MD docs. I am wondering what' the best thing to do here. Of course I can run --help and copy-paste but I'm not sure that's the best. I am trying to improve the documentation, not make it perfect :D Currently, it's quite out of date. I am not sure what's best. The full --help is also way too verbose and I don't think it's too helpful. They can always run it themselves. What do you think? Should I just copy-paste the --help and then explain the options as it is now (with common-options.md to explain the common ones)?

[msooseth]

Let me write a common-options.md to document some of the common options such as maxBufSize.

[msooseth]

Let me write a common-options.md to document some of the common options such as maxBufSize.

OK, I wrote a common-options.md now. It's not total, but it also doesn't have to be I think, it's a good start, I hope :)

[blishko]

It's definitely an improvement :)

I don't have any strong opinion on how to document the options, as I am not great with documentation myself.

[blishko]

LGTM!