search

Blueprint-uServices / blueprint

Blueprint Microservices Compiler: Flexible and Configurable Open-Source Microservice Benchmark Applications
https://blueprint-uservices.github.io
BSD 3-Clause "New" or "Revised" License
21 stars 5 forks source link

[Documentation] Documentation of applications and plugins (Jonathan) #118

Closed JonathanMace closed 10 months ago

JonathanMace commented 11 months ago

The main priority of documentation is as follows:

  1. Plugins Adding a package-level comment explaining the plugin. For plugins, we want to establish the convention that this goes in the wiring.go file. Elsewhere it should go in whatever location is sensible.
  2. Plugins Reducing the number of public structs and methods exposed by a plugin as much as possible, to make it easier for users. For example, the ideal case is that a plugin only exposes the wiring spec methods. In some cases more things will need to be exposed. But for now, refactor any public structs and methods to make them private, if they aren't used outside the plugin.
  3. Runtime core Runtime backend interfaces need as detailed comments as possible (both the interface and the package-level comment) because this is what developers will be referring to when writing application specs.
  4. Runtime plugins The constructors for backend instances would benefit from some documentation. Like with number 2. above, make as many structs and funcs as possible private.
  5. Application root Add a README in the root of the application briefly explaining what the application is, where it originated, how to compile it, what the wiring spec implementations are, how to run tests / workloads once the application is compiled, and how to add the compiled clients to your own code once the application is compiled.
  6. Workflow spec Make sure the interfaces and methods of a workflow spec have some comments. They don't need to be too detailed but they should explain what the service does, because this is most likely where a user will look if they want more information about the services within an application.
  7. Wiring specs For each wiring spec, make sure a comment exists somewhere that describes the basics of the spec (e.g. explains that it will deploy each service on grpc, etc. etc.).

Jonathan's TODO-list for documentation is as follows:

Applications:

JonathanMace commented 10 months ago

Implemented by b3bb75b