[webkit-efl] Question related to API comment location.

[Łukasz Ślachciak]

Hello Gyuyoung

We were discussing this in June on webkit-dev but in more broad 
approach. See Grzegorz proposition here:
https://lists.webkit.org/pipermail/webkit-dev/2011-June/thread.html#17246

There are two arguments of keeping documentation in cpp files:
1) when developer is working on function code he will not forget about 
updating documentation which is just in front of his eyes
2) changing header file causes more cpp files to be rebuild what makes 
building time longer

Argument 2) in my opinion is not important in current times.
Argument 1) is important but I think that advantages of keeping doc in 
.h file are more important:

1) dev packages with .h files will contain description so developers 
using webkit-efl-dev package don't need to check source code of cpp 
files when they want to know how to use given API

2) doxygen can generate documentation just using webkit-ef-dev package 
so there will be no need to have WebKit sources

3) it will be consistent with structures descriptions

Summing up:
Let's do this

Regards

Lukasz Slachciak

On 07/13/2011 04:32 AM, Gyuyoung Kim wrote:
> Hello,
>
> I wonder why API's description is added to .cpp files.
>
> For example, in ewk_view.cpp,
>
> /**
>   * Sets the spatial navigation.
>   *
>   * @param o view object to set spatial navigation setting.
>   * @return @c EINA_TRUE on success and @c EINA_FALSE on failure
>   */
> Eina_Bool ewk_view_setting_spatial_navigation_set(Evas_Object* o, Eina_Bool
> enable)
> {
>      EWK_VIEW_SD_GET_OR_RETURN(o, sd, EINA_FALSE);
>      EWK_VIEW_PRIV_GET_OR_RETURN(sd, priv, EINA_FALSE);
>      ...
> }
>
> In contrast, type definition's description are put on .h files.
>
> /**
>   * Cache (pool) that contains unused tiles for ewk_view_tiled.
>   *
>   * This cache will maintain unused tiles and flush them when the total
>   * memory exceeds the set amount when
>   * ewk_tile_unused_cache_auto_flush() or explicitly set value when
>   * ewk_tile_unused_cache_flush() is called.
>   *
>   * The tile may be shared among different ewk_view_tiled instances to
>   * group maximum unused memory resident in the system.
>   */
> typedef struct _Ewk_Tile_Unused_Cache Ewk_Tile_Unused_Cache;
>
>
> It looks there are no consistency for API description.
>
> IMO, it is better to move all descriptions to .h files. Because, application
> developers
> can refer to the usage of API through header files. If efl developers agree
> with my suggestion,
> I'd like to move all descriptions to header files.
>
> - Gyuyoung
>
>
>
> _______________________________________________
> webkit-efl mailing list
> webkit-efl at lists.webkit.org
> http://lists.webkit.org/mailman/listinfo.cgi/webkit-efl
>