Review Request 115325: Improve documentation of KWindowInfo

[Alex Merry]

-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://git.reviewboard.kde.org/r/115325/#review48701
-----------------------------------------------------------


I got fed up of making "As above" issues; the comments about one line brief descriptions then a line break then longer descriptions apply to the whole file.


src/kwindowinfo.h
<https://git.reviewboard.kde.org/r/115325/#comment34372>

    That is not how @link works (http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdlink).  You want
    @link KWindowSystem::windowChanged windowChanged at endlink
    (note the lack of space before @endlink - otherwise, the hyperlink extends to the following space).



src/kwindowinfo.h
<https://git.reviewboard.kde.org/r/115325/#comment34373>

    (eg: when using X11) or (eg: when using the X11 platform).



src/kwindowinfo.h
<https://git.reviewboard.kde.org/r/115325/#comment34374>

    Please make this
    
    Reads all the info about the given window.
    
    Only the information...
    
    (ie: a one-sentence line, then an empty line, then more detail, like a git commit message).



src/kwindowinfo.h
<https://git.reviewboard.kde.org/r/115325/#comment34375>

    Put the parentheses in the main body of the description (below the line break), not in the brief description



src/kwindowinfo.h
<https://git.reviewboard.kde.org/r/115325/#comment34376>

    Again, empty line between the sentences.  I would also remove the bit in parentheses, and instead put
    
    @see NET::State
    
    at the end (after @endcode)



src/kwindowinfo.h
<https://git.reviewboard.kde.org/r/115325/#comment34377>

    As above



src/kwindowinfo.h
<https://git.reviewboard.kde.org/r/115325/#comment34378>

    As above



src/kwindowinfo.h
<https://git.reviewboard.kde.org/r/115325/#comment34379>

    Doxygen doesn't like full stops in the brief comment, except at the end.  I think the bit about "the mainwindow for the window" should be in the longer description (after a one-line break) and should be more descriptive.



src/kwindowinfo.h
<https://git.reviewboard.kde.org/r/115325/#comment34371>

    Doxygen complains that these are undocumented; a brief "copy constructor"/"assignment operator" comment would shut it up.


- Alex Merry


On Jan. 27, 2014, 10:27 a.m., Martin Gräßlin wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://git.reviewboard.kde.org/r/115325/
> -----------------------------------------------------------
> 
> (Updated Jan. 27, 2014, 10:27 a.m.)
> 
> 
> Review request for KDE Frameworks.
> 
> 
> Repository: kwindowsystem
> 
> 
> Description
> -------
> 
> Improve documentation of KWindowInfo
> 
> The documentation was a little bit sparse and outdated.
> 
> 
> Diffs
> -----
> 
>   src/kwindowinfo.h 171f441ff329a5356ccf560341272199e20c837a 
> 
> Diff: https://git.reviewboard.kde.org/r/115325/diff/
> 
> 
> Testing
> -------
> 
> 
> Thanks,
> 
> Martin Gräßlin
> 
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kde-frameworks-devel/attachments/20140131/07b13030/attachment.html>