Review Request 119997: Add documentation to KConfig::sync()

[Martin Klapetek]

> 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.
> 
> Martin Klapetek wrote:
>     > 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.
> 
> Aleix Pol Gonzalez wrote:
>     Well, if @reimp is passed, it would mean that the parent documentation is good enough, no?

I thought that "@reimp" in doxygen marks the method as reimplemented from the parent class, ie. it adds a link to it. No?


- 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
> 
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kde-frameworks-devel/attachments/20140901/f6397ed5/attachment-0001.html>