Open sim642 opened 3 years ago
I see @michael-schwarz has just started documenting something for the SAS21 artifact (https://github.com/goblint/analyzer/tree/sas21_artifact_description), but we should probably have a broader strategy for this.
I strongly support the idea of documenting Goblint. :) I definitely want to help with this. We should pick the strategy that looks modern, is creates documentation that is easy to look through (well structured) and at the same time not causing use too much overhead to write and maintain. GitBook seems to me like a good solution.
I see @michael-schwarz has just started documenting something for the SAS21 artifact
Yes, we need to provide with the artifact a description of how to reproduce our results (for Validated
badge) and a description of the structure of the source code and how to extend it (for the Extensible
badge).
Generally, the goal to provide comprehensive documentation of Goblint is very laudable, but I fear that goal is very ambitious and we will fall short of it and our documentation will become out-of-sync with the code very soon.
Maybe something more realistic to aim for is the following three things:
Providing a tutorial for Goblint (similar to what Zach Anderson did for CIL), that should not get outdated as fast as comprehensive documentation. This document could be split into Using Goblint
and an Extending Goblint
sections and would e.g. serve as the starting point for students.
Equip every analysis with a description function unit -> string
that returns a string describing what it does that is printed for all registered analyses when running goblint -h
.
Try to be more strict with ourselves when it comes to naming variables and modules and structuring our code so it becomes self-documenting
Of course there's no point in writing massive documentation just for the sake of it when it's too much to keep up to date, but the tutorial-like use case is probably the reasonable thing I had in mind anyway. And it would be good to have a well-defined place where to keep the code structure description that we need for the artifact, so we're not practically throwing it away.
It's just that if there's no clear place for such documentation, it's absolutely sure that nobody will document such things. Such "Extending Goblint" section would also be a good place for all kinds of utility things, like a very short overview of how to use Pretty.printf
and all the Printable.pretty
functions instead of writing print_endline
stuff from scratch. There's a learning curve to some of these things, but no clear place to document them in the code if you already don't know about Cil.Pretty
and where to find its API documentation, for example.
One should also document:
I added these ideas into the issue itself, to have a nice TODO list at the top. If any others come about, feel free to edit the issue to extend the list.
I decided to set up Read the Docs now because it's actually quite unintrusive: all the documentation is based on the contents of the ./docs
directory and can also be browsed on GitHub directly.
I also wrote up a bunch of the ideas collected in this issue.
The conclusion is to use Read the Docs but documenting into
docs
directory of this repository in Markdown.Ideas for tutorial-style documentation
Pretty
--enable
/--disable
and--sets
) and conf filesgoblint/cil
locally and immediately using for Goblint.cilly
)[ ] Developing using VS Code
I've been thinking about this for a while that Goblint has no high-level documentation that describes its overall structure and functioning. Some parts of the source code are commented (and few have OCaml documentation comments) but neither is useful for users and new developers, because you already have to know where to find something or which terms to grep for.
Possible platforms
docs
directory.goblint-lib
is separated as a Dune library, Dune executables simply cannot have documentation).