Documentation of the different methods and parameters available in the pathfinder

[louilinn]

Can we add in the readme a summary of the parameters and what they mean in plain text?

Which parameters are available in CLI / server and what they do. Such as hops, maxTransfers etc.

This is essential for having a clear API documentation later on that will be used by various clients.

[almereyda]

This can be based on the existing documentation in https://hackmd.io/Gg04t7gjQKeDW2Q6Jchp0Q

pathfinder2/README.md

Line 21 in 4846da2

It implements the interface specified in https://hackmd.io/Gg04t7gjQKeDW2Q6Jchp0Q

pathfinder2/README.md

Line 54 in 4846da2

All data formats are described in https://hackmd.io/Gg04t7gjQKeDW2Q6Jchp0Q

Let's also keep in mind that the README is the primary entry point for developers who have no preliminary knowledge about the Parthfinder, and should therefore be complete in information or references to such. The README from the gh-pages branch is also used to render https://circlesubi.github.io/pathfinder2/, so it can be good to keep it in a good shape.

When merging the current dev to main, we could also build from that branch instead, reducing the maintenance overhead with the additional gh-pages branch, before even attempting an actual documentation website with a technical (API) reference and a human manual.

Also the CLI should ideally be self-describing, which counts as suitable documentation for me as well. @ingoCollatz has previoulsy volunteered to investigate improving on this end, when time comes. Currently there we have:

~/src/github.com/CirclesUBI/pathfinder2$ ./target/debug/cli --help
Usage: cli [--csv] [--safes] <from> <to> <edges.dat> [--dot <dotfile>]
Usage: cli [--csv] [--safes] <from> <to> <edges.dat> <max_hops>  [--dot <dotfile>]
Usage: cli [--csv] [--safes] <from> <to> <edges.dat> <max_hops> <max_flow> [--dot <dotfile>]
Usage: cli [--csv] [--safes] <from> <to> <edges.dat> <max_hops> <max_flow> <max_transfers> [--dot <dotfile>]
Option --csv reads edges.dat in csv format instead of binary.
Option --safes reads a safes.dat file instead of an edges.dat file.

~/src/github.com/CirclesUBI/pathfinder2$ ./target/debug/convert --help
Usage: convert <input> <input_file> <output> <output_file>
  Where <input> is one of:
    --safes-json
    --safes-bin
    --edges-csv
    --edges-bin
  and <output>is one of:
    --edges-csv
    --edges-bin

~/src/github.com/CirclesUBI/pathfinder2$ ./target/debug/server --help
thread 'main' panicked at 'Could not create server.: Error { kind: InvalidInput, message: "invalid socket address" }', src/server.rs:36:49
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Writing an actual man page could make life easier for some developers as well. Yet then the binary file names should eventually be reconsidered, to map well into a global $PATH.