[libkwineffects] Overhaul AnimationEffect's documentation
ClosedPublic

Authored by zzag on Dec 28 2018, 4:32 PM.

Details

Summary

This change reformats the documentation so it's more easier to read it.

Test Plan

Generated Doxygen documentation, started Python's Simple HTTP server, navigated
to AnimationEffect's documention, haven't noticed any serious issues.

Diff Detail

Repository
R108 KWin
Lint
Lint OK
Unit
No Unit Test Coverage
Build Status
Buildable 6408
Build 6426: arc lint + arc unit
zzag created this revision.Dec 28 2018, 4:32 PM
Restricted Application added a project: KWin. · View Herald TranscriptDec 28 2018, 4:32 PM
Restricted Application added a subscriber: kwin. · View Herald Transcript
zzag requested review of this revision.Dec 28 2018, 4:32 PM
zzag planned changes to this revision.Dec 28 2018, 4:38 PM

Reword genericAnimation's docs.

zzag updated this revision to Diff 48290.Dec 28 2018, 4:58 PM

reword

zzag retitled this revision from [libkwineffects] Reformat AnimationEffect's documentation to [libkwineffects] Overhaul AnimationEffect's documentation.Dec 28 2018, 4:59 PM
davidedmundson added inline comments.
libkwineffects/kwinanimationeffect.h
94

How are you generating the doxygen docs?

With typical KDE templates unless there's docs at the top of the class, it'll skip the entire thing, which makes any changes to make docs doxygen friendly a somewhat wasted effort.

zzag added inline comments.Dec 28 2018, 6:07 PM
libkwineffects/kwinanimationeffect.h
94

I used custom Doxyfile. Where can I find KDE's template?

zzag added inline comments.Dec 28 2018, 8:50 PM
libkwineffects/kwinanimationeffect.h
94

Alright, it seems like the one that comes with KApiDox.

zzag added a comment.Dec 28 2018, 9:06 PM

Huh, it looks like we follow neither https://community.kde.org/Policies/KDE4_Library_Documentation_Policy nor https://community.kde.org/Frameworks/Frameworks_Documentation_Policy in KWin and KWayland. E.g. we prefer

@param param Some description

over

@param param some description
zzag updated this revision to Diff 48324.Dec 28 2018, 10:23 PM

Add brief class docs

zzag updated this revision to Diff 48326.Dec 28 2018, 10:42 PM

Add missing @since

zzag updated this revision to Diff 48327.Dec 28 2018, 10:58 PM

More since

In D17832#383276, @zzag wrote:

KWin never followed those documents as KWin was neither a library in KDE 4 nor is it a framework. KWin's internal doxygen documentation predates these documents.

graesslin added inline comments.Dec 31 2018, 6:06 AM
libkwineffects/kwinanimationeffect.h
149–153

Constructs the AnimationEffect

152

the emphasis on not does not look like valid doxygen syntax

zzag updated this revision to Diff 48435.Dec 31 2018, 10:08 AM

Address Martin's inline comments.

zzag marked 2 inline comments as done.Dec 31 2018, 10:09 AM
zzag updated this revision to Diff 48436.Dec 31 2018, 10:23 AM

Reformat constructor's docs a little bit further.

davidedmundson accepted this revision.Jan 8 2019, 12:42 PM
This revision is now accepted and ready to land.Jan 8 2019, 12:42 PM
This revision was automatically updated to reflect the committed changes.