[prev in list] [next in list] [prev in thread] [next in thread] 

List:       koffice-devel
Subject:    Re: comments
From:       Jaroslaw Staniek <staniek () kde ! org>
Date:       2010-09-21 20:45:39
Message-ID: AANLkTikxpvQFXS-5az_8ZMM3kfTqYriz1cOB6iet2ni6 () mail ! gmail ! com
[Download RAW message or body]

On 21 September 2010 22:18, Thomas Zander <zander@kde.org> wrote:
> Jean-Nicolas gets a big hug and "commit of the week" for this :-)
> Such work is extremely valuable to make KOffice easier and more fun to work on
> and to be more inviting to new devs.
>
> Rock on Jean-Nicolas =)
>
> On Saturday 18. September 2010 11.29.39 Jean-Nicolas Artaud wrote:
>> SVN commit 1176694 by artaud:
>>
>> * Add plenty of comments
>>
>>
>>  M  +53 -3     KPrViewModeSlidesSorter.h
>>
>>
>> --- trunk/koffice/kpresenter/part/KPrViewModeSlidesSorter.h
>> #1176693:1176694 @@ -60,28 +60,80 @@
>>  protected:
>>
>>      /**
>> -    * Fills the editor with presentation slides and ordored them in the
>> KPrSlidesSorter +     * @brief Fills the editor with presentation slides
>> and ordored them in the KPrSlidesSorter */
>>      void populate();
>>
>> +    /**
>> +     * @brief Moves a page from pageNumber to pageAfterNumber
>> +     *
>> +     * @param pageNumber the number of the page to move
>> +     * @param pageAfterNumber the number of the place the page should move
>> to +     */
>>      void movePage( int pageNumber, int pageAfterNumber );
>>
>> +    /**
>> +     * @brief Getter for the count of the page
>> +     *
>> +     * @return the m_pageCount
>> +     */
>>      int pageCount();

Big thanks to Jean-Nicolas from me too!

One suggestion: this is a model example when the documentation is
redundant if not noisy:
- the method is getter by definition
- m_pageCount is the implementation detail that SHOULD be hidden from the reader
- BTW: if this is getter, why isn't this a const method?
- doxygen note: @brief is not needed if you use just one-liner doc
(what would be the case if the above suggestions were accepted)


[..]

>> +    /**
>> +     * @brief Setter of the last item number it were on
>> +     *
>> +     * @param number of the item number it is on

grammar...

Thanks.

-- 
regards / pozdrawiam, Jaroslaw Staniek
 http://www.linkedin.com/in/jstaniek
 Kexi & KOffice (http://kexi-project.org, http://identi.ca/kexi,
http://koffice.org)
 KDE Software Development Platform on MS Windows (http://windows.kde.org)
_______________________________________________
koffice-devel mailing list
koffice-devel@kde.org
https://mail.kde.org/mailman/listinfo/koffice-devel

[prev in list] [next in list] [prev in thread] [next in thread]