Skip to content

docs: dbus: add DBus API documentation #145

Draft
artiepoole wants to merge 12 commits intomainfrom
artie/document_interfaces
Draft

docs: dbus: add DBus API documentation #145
artiepoole wants to merge 12 commits intomainfrom
artie/document_interfaces

Conversation

@artiepoole
Copy link
Contributor

@artiepoole artiepoole commented Jan 8, 2026 •
edited
Loading

DBus module documentation added for:

  • helper functions
  • StatusInterface
  • ControlInterface

Documentation added at

  • top level
  • class level
  • function level

I also

  • standardised the name for the platform string variable to platform_string, replacing usages of platform_compat_str
  • removed 2 unused imports from cli/main.rs (clap's arg and command) to pass code formatting checks
  • added a CLI toplevel doc (copied/moved from readme)
  • removed a print of raw byte strings to terminal (mostly gonna be lossy characters)

edit: moved these unrelated changes into #150

@github-actions github-actions bot added the cli label Jan 8, 2026
@artiepoole artiepoole linked an issue Jan 8, 2026 that may be closed by this pull request
docs: interfaces are not documented #144
Open
@artiepoole artiepoole added documentation Improvements or additions to documentation comm dbus labels Jan 8, 2026
@artiepoole artiepoole assigned artiepoole and unassigned artiepoole Jan 8, 2026
@artiepoole artiepoole force-pushed the artie/document_interfaces branch 2 times, most recently from 30b70d4 to d89f332 Compare January 8, 2026 17:28
@artiepoole artiepoole requested a review from hkhonming January 8, 2026 17:29
@artiepoole artiepoole marked this pull request as ready for review January 15, 2026 10:17
talhaHavadar
talhaHavadar requested changes Jan 15, 2026
View reviewed changes
daemon/src/comm/dbus/README.md Outdated
Copy link
Collaborator

@talhaHavadar talhaHavadar Jan 15, 2026

Choose a reason for hiding this comment

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

I think we could add all these documentation as rust docstring to the relevant places/functions etc. and then use rust docs to refer in readme which would have better interface and would be easier to maintain since the doc would reside with code

Copy link
Contributor Author

@artiepoole artiepoole Jan 15, 2026

Choose a reason for hiding this comment

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

That's actually a very good idea.

Can we host the docs here in the repo, and build them on merge or something (automation)?

Copy link
Collaborator

@talhaHavadar talhaHavadar Jan 15, 2026

Choose a reason for hiding this comment

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

I think we can and actually if we publish this to cargo it will automatically have docs.rs page for us

Copy link
Collaborator

@talhaHavadar talhaHavadar Jan 15, 2026

Choose a reason for hiding this comment

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

I think I registered the name for fpgad in cargo gonna add you as owner as well let me check

@artiepoole artiepoole force-pushed the artie/document_interfaces branch from d89f332 to 1654535 Compare January 19, 2026 18:12
@github-actions github-actions bot added the root label Jan 19, 2026
@github-actions github-actions bot requested a review from talhaHavadar January 19, 2026 18:12
@artiepoole
Copy link
Contributor Author

artiepoole commented Jan 19, 2026 •
edited
Loading

I have documented the code as suggested. I removed the original API readme. I also discovered an issue - we were writing out the requested data after writing it in fs_write_bytes - this is not good practice so I stopped this. I think we should also not do this in fs_write either. (it's great for debugging, sure, but "n_bytes" or just "succeeded" is better.
Let me know what you think. here

As for the documentation - check out my branch and run cargo doc et voila!

@artiepoole artiepoole force-pushed the artie/document_interfaces branch 2 times, most recently from d7a5734 to 001157a Compare January 21, 2026 17:13
@artiepoole
comm: dbus: use platform_string everywhere instead of platform_compat…
76a33bd 
…_str

The use of platform_compat_str and platform_string was inconsistent, and
not very critical, so I have chosen to use platform_string everywhere

Signed-off-by: Artie Poole <stuart.poole@canonical.com>
@artiepoole
cli: main.rs - remove unused imports
ab5782b 
necessary to pass inspection after updating clippy

Signed-off-by: Artie Poole <stuart.poole@canonical.com>
@artiepoole
dbus: don't print raw bytes on fs_write_bytes
7d9cec8 
these are messy, and also could leak secure information

Signed-off-by: Artie Poole <stuart.poole@canonical.com>
@artiepoole
cli: proxies - remove non-existent function get_platform_name
afd525f 
Signed-off-by: Artie Poole <stuart.poole@canonical.com>
@artiepoole artiepoole force-pushed the artie/document_interfaces branch from 001157a to a0c1a68 Compare January 22, 2026 13:58
@artiepoole artiepoole changed the base branch from main to artie/remove_bad_prints January 22, 2026 13:59
@artiepoole artiepoole marked this pull request as draft January 22, 2026 13:59
@artiepoole
root: error.rs stop printing raw data to logs - could be sensitive
4651f67 
Signed-off-by: Artie Poole <stuart.poole@canonical.com>
@artiepoole
root: add cargo mutants output to gitignore
79089f0 
Signed-off-by: Artie Poole <stuart.poole@canonical.com>
@artiepoole
cli: load - remove panic code path from sanitize_path_str
da7d5bc 
Signed-off-by: Artie Poole <stuart.poole@canonical.com>
@artiepoole artiepoole force-pushed the artie/remove_bad_prints branch from c523cc4 to da7d5bc Compare January 22, 2026 14:10
@artiepoole artiepoole force-pushed the artie/document_interfaces branch from a0c1a68 to 0278039 Compare January 22, 2026 14:11
@artiepoole
workflows: pin submit version to use proxy (rev263)
33867ae 
Signed-off-by: Artie Poole <stuart.poole@canonical.com>
@artiepoole
docs: document the dbus module
ddbf0df 
documentation added for:
- helper functions
- StatusInterface
- ControlInterface

Documentation added at
- top level
- class level
- function level

Signed-off-by: Artie Poole <stuart.poole@canonical.com>
@artiepoole
docs: CLI add top level docstring
f44d7a2 
Signed-off-by: Artie Poole <stuart.poole@canonical.com>
@artiepoole
docs: fix misinformation in daemon busctl examples
a56b89b 
the hex value is returned as undecorated ascii (no 0x prefix)

Signed-off-by: Artie Poole <stuart.poole@canonical.com>
@artiepoole
docs: document the static variables in config.rs
7bcdfc5 
Signed-off-by: Artie Poole <stuart.poole@canonical.com>
@artiepoole artiepoole force-pushed the artie/document_interfaces branch from 0278039 to 7bcdfc5 Compare February 19, 2026 14:57
Base automatically changed from artie/remove_bad_prints to main February 19, 2026 21:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hkhonming hkhonming Awaiting requested review from hkhonming

@talhaHavadar talhaHavadar Awaiting requested review from talhaHavadar

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

cli documentation Improvements or additions to documentation root

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs: interfaces are not documented

2 participants

@artiepoole @talhaHavadar