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

[Grzegorz Czajkowski]

Hello,

I am preparing a patch which moves API documentation from cpp to the header
files.
Is there a chance for review that huge patch? Or do you prefer smaller
patches?

Regards
Grzegorz

-----Original Message-----
From: webkit-efl-bounces at lists.webkit.org
[mailto:webkit-efl-bounces at lists.webkit.org] On Behalf Of Gyuyoung Kim
Sent: 13 July 2011 10:25
To: 'Łukasz Ślachciak'
Cc: webkit-efl at lists.webkit.org
Subject: Re: [webkit-efl] Question related to API comment location.

Hello Lukasz,

Thank you for your kindly reply. I also think API description in .h files
has more advantages.
If nobody prepares patches for this, I'm going to file a bug.

- Gyuyoung 

> -----Original Message-----
> From: webkit-efl-bounces at lists.webkit.org [mailto:webkit-efl-
> bounces at lists.webkit.org] On Behalf Of Łukasz ?lachciak
> Sent: Wednesday, July 13, 2011 5:01 PM
> To: webkit-efl at lists.webkit.org
> Subject: Re: [webkit-efl] Question related to API comment location.
> 
> 
> 
> 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
> >
> 
> _______________________________________________
> webkit-efl mailing list
> webkit-efl at lists.webkit.org
> http://lists.webkit.org/mailman/listinfo.cgi/webkit-efl

_______________________________________________
webkit-efl mailing list
webkit-efl at lists.webkit.org
http://lists.webkit.org/mailman/listinfo.cgi/webkit-efl