D21266: [WIP] Improve documentation of area classes

[Albert Astals Cid]

aacid added inline comments.

INLINE COMMENTS

> area.h:36
>   * of a normalized point. Normalized means that the coordinates are
> - * between 0 and 1 so that it is page size independent.
> + * between 0 and 1, independent of the page size.
>   *

i don't see why your version of the text is better.

> area.h:47
>   *
> - *    That allows you to zoom the page by just multiplying the normalized points with the
> - *    zoomed page size.
> + * If you zoom a page to 800x600 pixels and want do draw the point on it,
> + * just multiply the x coordinate (0.5) with the page width (800),

zoom doesn't seem the appropiate word here, there's no zooming involved

> area.h:69
>          /**
> -         * Creates a new empty normalized point.
> +         * Creates the normalized point at (0, 0).
>           */

why "the" ?

> area.h:80
> +         * Creates a new normalized point from an absolute point (@p x, @p y)
> +         * on a page of size @p xScale x @p yScale.
>           */

I don't like that you mention a page here.

> area.h:98
>          /**
> -         * Returns squared distance to point @p x @p y @p xScale @p yScale
> +         * Returns squared distance to normalized point (@p x, @p y) at a page size of @p xScale x @p yScale.
>           * @since 0.17 (KDE 4.11)

same, this is not striclty page related

> area.h:125
> + *
> + * It describes a rectangular area on a page, independent of the page size or zoom.
> + * Like NormalizedPoint, it can be scaled to absolute page sizes.

Again this is not strictly page related, can be used for anything please don't refer to pages other than as "for example"

> area.h:128
> + *
> + * Currently, NormalizedRect is used to describe the position of TextEntitys (glyphs, words, lines, ...)
> + * and the highlight area of text selections.

This information makes no sense here.

> area.h:131
> + *
> + * RegularAreaRect is a list of NormalizedRects, so more complex shapes can be described,
> + * also independent of the page size or zoom.

What a regularAreaRect is doesn't belong to the description of NormalizedRect (imho, the @see is fine)

> area.h:872
> + *
> + * Given a page size, the area can be converted to a list of QRects with absolute coordinates.
> + *

This comment is weird, it seems to imply such functionality exists in this class, when it doesn't.

REPOSITORY
  R223 Okular

REVISION DETAIL
  https://phabricator.kde.org/D21266

To: davidhurka, #okular
Cc: aacid, okular-devel, joaonetto, tfella, ngraham, darcyshen
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/okular-devel/attachments/20190519/2f6acd56/attachment-0001.html>