Skip to content

Add mlis for observer_helpers and observer_skeleton #6539

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

snwoods
Copy link
Contributor

@snwoods snwoods commented Jun 17, 2025

No description provided.

@psafont
Copy link
Member

psafont commented Jun 17, 2025

We probably want to add some documentation-comments to the type signatures here

Copy link
Contributor

@lindig lindig left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some functions have multiple string parameters, no labels, and no documentation.

@snwoods snwoods force-pushed the private/stevenwo/observer_helpers_mli branch from 8ec5b90 to 663c08d Compare June 25, 2025 09:03
@snwoods
Copy link
Contributor Author

snwoods commented Jun 25, 2025

Some functions have multiple string parameters, no labels, and no documentation.

They are all based on the ObserverAPI module, but that's an RPC interface definition using declare , which I don't think I can label, so I don't know what the best way to do this would be? I could add a documentation string for each function like:
(** Creates an observer

  • debug_info
  • uuid
  • name_label
    ...
    *) ?
    But I don't know how helpful that would be, or if I should just point to other documentations of an Observer e.g. Xapi_observer or ocaml/libs/tracing ? I have also labelled the parameters in Server_impl module below and they are the same parameters.

@psafont
Copy link
Member

psafont commented Jun 25, 2025

Documenting them is good, see how parameters are documented in many of the interface files, this one for example: https://github.com/xapi-project/xen-api/blob/master/ocaml/xapi-idl/xen/device_number.mli#L23

@snwoods snwoods force-pushed the private/stevenwo/observer_helpers_mli branch from 663c08d to e424f75 Compare June 25, 2025 12:02
Comment on lines +38 to +40
(** [create dbg uuid name attributes endpoints enabled] is for when the
Observer is created. [uuid] is the Observer which has been created and
the parameters following are the fields the Observer was created with. *)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This wording is a bit strange, usually what's explained is the expected result in terms of the input, something like:

Suggested change
(** [create dbg uuid name attributes endpoints enabled] is for when the
Observer is created. [uuid] is the Observer which has been created and
the parameters following are the fields the Observer was created with. *)
(** [create dbg uuid name attributes endpoints enabled] creates an
Observer with UUID [uuid]. *)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants