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

Fri Jul 15 05:14:27 PDT 2011

Hi Ryuan,

I think we need to move documentation to the header files first, without any modification of current one.

Of course your proposition is worth the effort. We can prepare another patch for this.

Regards

Grzegorz

From: Ryuan Choi [mailto:ryuan.choi at samsung.com] 
Sent: 15 July 2011 13:22
To: g.czajkowski at samsung.com
Cc: webkit-efl at lists.webkit.org
Subject: Re: Re: [webkit-efl] Question related to API comment location.

Hello, grzegorz

A few minutes ago, I discussed somthing about doxygen with kangil han.

He want @file, @brief in header files to prepare doxygen document.

How do you think about adding doxygen attributes ( '@file', '@brief') when you prepared patch you mentioned.

Regards,

Ryuan Choi

------- Original Message -------

Sender : Grzegorz Czajkowski<g.czajkowski at samsung.com> Junior Software Engineer/Poland R&D Center-Linux (MSD)/삼성전자

Date : 2011-07-15 15:26 (GMT+09:00)

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

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

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-efl/attachments/20110715/5edd95ee/attachment-0001.html>