> On Aug. 31, 2014, 6:57 a.m., Matthew Dawson wrote: > > Thanks for taking a look at this. It appears KConfigBase isn't available > > on api.kde.org as it isn't documented, as kapidox hides such classes by > > default. As KConfigBase is used outside of KConfig, I'd prefer if > > KConfigBase gained a quick blurb to copying its documentation. I think > > something describing it as a way for a function to accept either a KConfig > > or a KConfigGroup and be able load/persist its settings would be good. > > Martin Klapetek wrote: > KConfigBase is very much documented, see [1]. I don't know why it's not > showing up...nevertheless, if that method is reimplementation of the base > class method, it should imho has its own documentation altogether (it's > *reimplementation* after all). What I did here is just a quick fix to improve > that... > > [1] - > http://quickgit.kde.org/?p=kconfig.git&a=blob&h=3d00d98a1eb565df1a6eea2eba165bfeda17978b&hb=5941a608038d799244ba2dfdceb2da8bf1685fc1&f=src%2Fcore%2Fkconfigbase.h > > Matthew Dawson wrote: > While class members of KConfigBase are documented, Doxygen doesn't > consider it documented as the class itself does not have a description > attached. Attaching even a brief line convinces Doxygen otherwise. > > Regarding each method having its own documentation, I took a quick look > through the other code I have checked out on my machine, and it appears most > classes don't copy the documentation from their parent. I couldn't find any > policy on this either from KDE's website. If we want each function in > frameworks to be fully documented, without having to click a reference, then > I'm fine with this patch. This should then probably get documnted on the > community wiki, so others know for the future to include it. > > However, if this patch came from the fact KConfigBase is not on > api.kde.org, then I rather fix this by throwing a quick description on > KConfigBase. Then the sync method's documentation does show up, and a link > is generated on KConfig's sync method making it easy to read. Maybe > something like: > > \brief Interface to interact with configuration. > > KConfigBase allow a component of an application to persist its > configuration, without having to care if it persists its data into a top > level KConfig, or a KConfigGroup inside a KConfig.
> it appears most classes don't copy the documentation from their parent. Right; my point is that a reimplementation of an abstract class method/interface method is usually a specific implementation of the broad parent abstract class meaning. > If we want each function in frameworks to be fully documented... if this > patch came from the fact KConfigBase is not on api.kde.org In the light of what I wrote above, my intention was a little bit of both. - Martin ----------------------------------------------------------- This is an automatically generated e-mail. To reply, visit: https://git.reviewboard.kde.org/r/119997/#review65567 ----------------------------------------------------------- On Aug. 29, 2014, 11:42 p.m., Martin Klapetek wrote: > > ----------------------------------------------------------- > This is an automatically generated e-mail. To reply, visit: > https://git.reviewboard.kde.org/r/119997/ > ----------------------------------------------------------- > > (Updated Aug. 29, 2014, 11:42 p.m.) > > > Review request for KDE Frameworks. > > > Repository: kconfig > > > Description > ------- > > The docs at api.kde.org shows just "Reimplemented from superclass." for the > sync() method, however the superclass, KConfigBase, is not available at the > api.kde.org. So this copies the documentation from KConfigBase to KConfig so > the text can actually be visible at api.kde.org > > > Diffs > ----- > > src/core/kconfig.h d7d4b7d > > Diff: https://git.reviewboard.kde.org/r/119997/diff/ > > > Testing > ------- > > > Thanks, > > Martin Klapetek > >
_______________________________________________ Kde-frameworks-devel mailing list [email protected] https://mail.kde.org/mailman/listinfo/kde-frameworks-devel
