Improve documentation
ClosedPublic

Authored by gladhorn on Sep 12 2019, 7:35 PM.

Details

Reviewers
romangg
Group Reviewers
KWin
Commits
R127:6388d550e3a2: Improve documentation
Summary

Some of the documentation did not say what the purpose of the
respective class was, but rather gave a tautology.
For people new to the code base it helps to mention that
DPMS is power management.

That DataDevice is for copy-and-paste and drag-and-drop is
maybe obvious to people used to X11 API, but not very clear
to most others.

When first reading the KWayland code, some explanations
help getting around.

Diff Detail

Repository
R127 KWayland
Branch
arcpatch-D23915_1
Lint
Lint OK
Unit
No Unit Test Coverage
Build Status
Buildable 16543
Build 16561: arc lint + arc unit
gladhorn created this revision.Sep 12 2019, 7:35 PM
Restricted Application added a project: Frameworks. · View Herald TranscriptSep 12 2019, 7:35 PM
Restricted Application added a subscriber: kde-frameworks-devel. · View Herald Transcript
gladhorn requested review of this revision.Sep 12 2019, 7:35 PM
zzag added a subscriber: zzag.Sep 13 2019, 8:31 AM
zzag added inline comments.
src/client/dpms.h
44

Not sure that this is valid documentation for org_kde_kwin_dpms_manager because it's nothing more but a factory.

src/server/dpms_interface.h
38–43

While it's sort of true, I don't think it's valid description. The line above precisely describes what DpmsManagerInterface is.

romangg accepted this revision.Sep 13 2019, 9:53 AM
romangg added a subscriber: romangg.
romangg added inline comments.
src/client/dpms.h
44

Yea, maybe just write that this class is meant to create the DPMS object below only. You already have the information you provided here there then.

src/server/dpms_interface.h
38–43

Not sure why it should not be valid. Maybe add that the code interaction server-side happens only via the OutputInterface. Because client-side in KWayland the respective Dpms class provides the API.

This revision is now accepted and ready to land.Sep 13 2019, 9:53 AM
gladhorn updated this revision to Diff 66026.Sep 14 2019, 9:06 AM
gladhorn retitled this revision from Add some docstrings to Improve documentation Some of the documentation did not say what the purpose of the respective class was, but rather gave a tautology. For people new to the code base it helps to mention that DPMS is power management. That DataDevice is for copy....
gladhorn edited the summary of this revision. (Show Details)

Updating D23915: Improve documentation

Some of the documentation did not say what the purpose of the
respective class was, but rather gave a tautology.
For people new to the code base it helps to mention that
DPMS is power management.

That DataDevice is for copy...

gladhorn added inline comments.Sep 14 2019, 9:07 AM
src/client/dpms.h
44

I agree. The first two lines are actually repetitions and they don't say what the class is good for at all. I'll update this.

romangg requested changes to this revision.Sep 14 2019, 9:27 AM

Title of this diff must be changed before push.

This revision now requires changes to proceed.Sep 14 2019, 9:27 AM
gladhorn updated this revision to Diff 66078.Sep 14 2019, 5:57 PM
gladhorn retitled this revision from Improve documentation Some of the documentation did not say what the purpose of the respective class was, but rather gave a tautology. For people new to the code base it helps to mention that DPMS is power management. That DataDevice is for copy... to Improve documentation.
gladhorn edited the summary of this revision. (Show Details)

Thank you arc for messing up my commit message XD

romangg accepted this revision.Sep 15 2019, 6:56 PM
This revision is now accepted and ready to land.Sep 15 2019, 6:56 PM
This revision was automatically updated to reflect the committed changes.