Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-11-25 Thread Stefan Schmidt 
Hello.

On 24/11/16 23:33, Gustavo Sverzut Barbieri wrote:
> Plus reference to events, as it will be hard to add afterwards. See all
> io/net where I try to document their relation to methods

Jpeg also raised this point before. Daniel is looking into this. AFAIK 
he was thinking about the best syntax to use for this which would not 
clash with other reference e.g. same name for event and function.

> Also, it would be nice to extend or replace docs for methods we implement.
> Clear user is "dial(address)" where I'd like to document address string
> encoding for each protocol.

I think Daniel was thinking about this as well. No more details from my 
side on this. Daniel, any comments?

regards
Stefan Schmidt

--
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel

Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-11-24 Thread Gustavo Sverzut Barbieri 
Plus reference to events, as it will be hard to add afterwards. See all
io/net where I try to document their relation to methods

Also, it would be nice to extend or replace docs for methods we implement.
Clear user is "dial(address)" where I'd like to document address string
encoding for each protocol.


Em qui, 24 de nov de 2016 às 19:31, Stefan Schmidt 
escreveu:

> Hello.
>
> On 24/11/16 19:38, Felipe Magno de Almeida wrote:
> > On Thu, Nov 24, 2016 at 1:35 PM, Stefan Schmidt 
> wrote:
> >> Hello.
> >
> > [snip]
> >
> >> With the last batch I pushed today we have 100% doc coverage in our eo
> >> files! :)
> >>
> >> Now we need to keep it like this, please. :)
> >
> > Great job!
> > Why not have Daniel add an error for functions that are not documented
> in Eo?
>
> Sometimes it needs someone else to speak out the obvious thing. Thanks! :)
>
> Daniel, can you do this? Print out an error message sayung that
> documentation is missing should be enough to give people an idea whats
> going on. We have enough examples in tree now.
>
> regards
> Stefan Schmidt
>
>
> --
> ___
> enlightenment-devel mailing list
> enlightenment-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
>
--
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel

Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-11-24 Thread Stefan Schmidt 
Hello.

On 24/11/16 19:38, Felipe Magno de Almeida wrote:
> On Thu, Nov 24, 2016 at 1:35 PM, Stefan Schmidt  
> wrote:
>> Hello.
>
> [snip]
>
>> With the last batch I pushed today we have 100% doc coverage in our eo
>> files! :)
>>
>> Now we need to keep it like this, please. :)
>
> Great job!
> Why not have Daniel add an error for functions that are not documented in Eo?

Sometimes it needs someone else to speak out the obvious thing. Thanks! :)

Daniel, can you do this? Print out an error message sayung that 
documentation is missing should be enough to give people an idea whats 
going on. We have enough examples in tree now.

regards
Stefan Schmidt

--
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel

Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-11-24 Thread Felipe Magno de Almeida 
On Thu, Nov 24, 2016 at 1:35 PM, Stefan Schmidt  wrote:
> Hello.

[snip]

> With the last batch I pushed today we have 100% doc coverage in our eo
> files! :)
>
> Now we need to keep it like this, please. :)

Great job!
Why not have Daniel add an error for functions that are not documented in Eo?

[snip]

> regards
> Stefan Schmidt

Regards,
-- 
Felipe Magno de Almeida

--
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel

Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-11-24 Thread Jérémy Zurcher 
On Thursday 24 November 2016  16:35, Stefan Schmidt wrote :
> Hello.
> 
> On 25/10/16 10:15, Stefan Schmidt wrote:
> > Hello.
> >
> > On 25/10/16 05:04, Carsten Haitzler (The Rasterman) wrote:
> >> On Sat, 22 Oct 2016 00:43:30 +0200 Stefan Schmidt  
> >> said:
> >>
> >>> Hello.
> >>>
> >>> TL;DR: If you are committing new eo files I expect them to have full
> >>> docs from now one. Also help with the ones you are currently working on.
> >>
> >> this is actually looking pretty decent below now in terms of progress. :)
> >
> > Indeed. :)
> >
> > With some more patches I've been working on right now I'm at 80% total
> > coverage.
> 
> With the last batch I pushed today we have 100% doc coverage in our eo 
> files! :)


+WaôaW+ ! very good job indeed.


> 
> Now we need to keep it like this, please. :)
> 
> The next steps from my side are to get these docs with the new doc 
> system from Daniel deployed to our E server to make it available to 
> everyone. Once that is done we need to improve the docs for consistency 
> and quality in general.
> 
> regards
> Stefan Schmidt
> 
> --
> ___
> enlightenment-devel mailing list
> enlightenment-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
--- Hell'O from Yverdoom

Jérémy (jeyzu)

--
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel

Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-11-24 Thread Stefan Schmidt 
Hello.

On 25/10/16 10:15, Stefan Schmidt wrote:
> Hello.
>
> On 25/10/16 05:04, Carsten Haitzler (The Rasterman) wrote:
>> On Sat, 22 Oct 2016 00:43:30 +0200 Stefan Schmidt  
>> said:
>>
>>> Hello.
>>>
>>> TL;DR: If you are committing new eo files I expect them to have full
>>> docs from now one. Also help with the ones you are currently working on.
>>
>> this is actually looking pretty decent below now in terms of progress. :)
>
> Indeed. :)
>
> With some more patches I've been working on right now I'm at 80% total
> coverage.

With the last batch I pushed today we have 100% doc coverage in our eo 
files! :)

Now we need to keep it like this, please. :)

The next steps from my side are to get these docs with the new doc 
system from Daniel deployed to our E server to make it available to 
everyone. Once that is done we need to improve the docs for consistency 
and quality in general.

regards
Stefan Schmidt

--
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel

Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-10-25 Thread The Rasterman 
On Tue, 25 Oct 2016 10:15:52 +0200 Stefan Schmidt  said:

> Hello.
> 
> On 25/10/16 05:04, Carsten Haitzler (The Rasterman) wrote:
> > On Sat, 22 Oct 2016 00:43:30 +0200 Stefan Schmidt 
> > said:
> >
> >> Hello.
> >>
> >> TL;DR: If you are committing new eo files I expect them to have full
> >> docs from now one. Also help with the ones you are currently working on.
> >
> > this is actually looking pretty decent below now in terms of progress. :)
> 
> Indeed. :)
> 
> With some more patches I've been working on right now I'm at 80% total 
> coverage. In the process I also try to sort out some in-consistencies of 
> wording when i spot them, but quality wise there is still a lot to be 
> done which hopefully comes in a second phase.

thumbs up on this. very good. :)


-- 
- Codito, ergo sum - "I code, therefore I am" --
The Rasterman (Carsten Haitzler)ras...@rasterman.com


--
The Command Line: Reinvented for Modern Developers
Did the resurgence of CLI tooling catch you by surprise?
Reconnect with the command line and become more productive. 
Learn the new .NET and ASP.NET CLI. Get your free copy!
http://sdm.link/telerik
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel

Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-10-25 Thread Stefan Schmidt 
Hello.

On 25/10/16 05:04, Carsten Haitzler (The Rasterman) wrote:
> On Sat, 22 Oct 2016 00:43:30 +0200 Stefan Schmidt  
> said:
>
>> Hello.
>>
>> TL;DR: If you are committing new eo files I expect them to have full
>> docs from now one. Also help with the ones you are currently working on.
>
> this is actually looking pretty decent below now in terms of progress. :)

Indeed. :)

With some more patches I've been working on right now I'm at 80% total 
coverage. In the process I also try to sort out some in-consistencies of 
wording when i spot them, but quality wise there is still a lot to be 
done which hopefully comes in a second phase.

regards
Stefan Schmidt

--
The Command Line: Reinvented for Modern Developers
Did the resurgence of CLI tooling catch you by surprise?
Reconnect with the command line and become more productive. 
Learn the new .NET and ASP.NET CLI. Get your free copy!
http://sdm.link/telerik
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel

Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-10-24 Thread The Rasterman 
On Sat, 22 Oct 2016 00:43:30 +0200 Stefan Schmidt  said:

> Hello.
> 
> TL;DR: If you are committing new eo files I expect them to have full 
> docs from now one. Also help with the ones you are currently working on.

this is actually looking pretty decent below now in terms of progress. :)

> Longer version:
> If you look at the commit log you can see that I started another crusade 
> on getting our doc coverage for eo files.
> 
> Right now we have the following stats for our documentation efforts:
> 
> === CLASS SECTION: 269 out of 864 (31%) ===
> 
> Classes:   255 (documented:   93 or  36%)
> Interfaces: 57 (documented:   22 or  39%)
> Mixins: 28 (documented:   28 or 100%)
> Events:524 (documented:  126 or  24%)
> 
> === FUNCTION SECTION: 6440 out of 7790 (83%) ===
> 
> Methods:  1016 (documented:  936 or  92%)
>Method params:  1667 (documented: 1401 or  84%)
>Method returns:  493 (documented:  310 or  63%)
> Getters:  1059 (documented:  970 or  92%)
>Getter returns:  175 (documented:  105 or  60%)
>Getter keys: 120 (documented:   89 or  74%)
>Getter values:  1197 (documented:  924 or  77%)
> Setters:   845 (documented:  779 or  92%)
>Setter returns:   69 (documented:   43 or  62%)
>Setter keys:  57 (documented:   49 or  86%)
>Setter values:  1092 (documented:  834 or  76%)
> 
> === TYPE SECTION: 1240 out of 1775 (70%) ===
> 
> Aliases:84 (documented:9 or  11%)
> Structs:82 (documented:   57 or  70%)
> Struct fields: 191 (documented:  156 or  82%)
> Enums: 170 (documented:  154 or  91%)
> Enum fields:  1248 (documented:  864 or  69%)
> 
> === VARIABLE SECTION: 56 out of 56 (100%) ===
> 
> Constants:   0 (documented:0 or 100%)
> Globals:56 (documented:   56 or 100%)
> 
> === TOTAL: 8005 out of 10485 (76%) ===
> 
> Which means we have 2480 undocumented items.
> 
> I'm willing to work on this and I actually doing it already but if your 
> working area covers some eo files please make sure that you document all 
> bits in there. Some might look silly on a first glace (enums fields, 
> etc) but getting this to a 100% coverage, and keeping it, really helps 
> the doc efforts. We are using these to generate our documentation and 
> after some time for setup and migration of the older doxygen docs we 
> will switch to them. An example how they look like is here (design and 
> layout is up for suggestions but need to stay aligned with our www theme 
> to have a consistent look):
> https://devs.enlightenment.org/~stefan/dokuwiki/doku.php?id=docs:efl:auto:reference
> 
> To keep track on the progress you can use:
> src/bin/elua/elua src/scripts/elua/apps/gendoc.lua -src/lib/
> 
> To get an output of what items are still need docs use the verbose flag:
> src/bin/elua/elua src/scripts/elua/apps/gendoc.lua -v src/lib/
> 
> regards
> Stefan Schmidt
> 
> --
> Check out the vibrant tech community on one of the world's most 
> engaging tech sites, SlashDot.org! http://sdm.link/slashdot
> ___
> enlightenment-devel mailing list
> enlightenment-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
> 


-- 
- Codito, ergo sum - "I code, therefore I am" --
The Rasterman (Carsten Haitzler)ras...@rasterman.com


--
The Command Line: Reinvented for Modern Developers
Did the resurgence of CLI tooling catch you by surprise?
Reconnect with the command line and become more productive. 
Learn the new .NET and ASP.NET CLI. Get your free copy!
http://sdm.link/telerik
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel

Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-10-24 Thread Stefan Schmidt 
Hello.

On 24/10/16 10:27, Stefan Schmidt wrote:
> Hello.
>
> On 24/10/16 05:15, Jean-Philippe André wrote:
>> Hi Stefan,
>>
>> On 22 October 2016 at 07:43, Stefan Schmidt  wrote:
>>
>> I assume gendoc.lua should be run against /share/eolian/include
>> rather than the internal lib folder?
>
> Well, with your effort to remove many of the unnecessary installed EO
> files this makes sense. So far it did not really make much of a
> difference thought and allowed for quicker testing (no need to make sure
> all old EO files are removed and installing the latest before running
> docgen)
>
>> This unfortunately fails with "bad argument #2 to
>> 'eolian_function_scope_get' (cannot convert 'nil' to 'unsigned int')".
>
> Hmm, I will see if I can reproduce this. Maybe Daniel does know more.

I had to remove all installed eo files first but after this and a frsh 
install of efl it works for me:

stefan@workmachine efl (master) $ find /usr/local/ -name *.eo | wc -l
323
stefan@workmachine efl (master) $ elua 
/usr/local/share/elua/apps/gendoc.lua /usr/local/share/eolian/include/
=== CLASS SECTION: 263 out of 843 (31%) ===

Classes:   240 (documented:   88 or  37%)
Interfaces: 55 (documented:   21 or  38%)
Mixins: 28 (documented:   28 or 100%)
Events:520 (documented:  126 or  24%)

=== FUNCTION SECTION: 6053 out of 7309 (83%) ===

Methods:   940 (documented:  861 or  92%)
   Method params:  1519 (documented: 1293 or  85%)
   Method returns:  451 (documented:  286 or  63%)
Getters:  1015 (documented:  934 or  92%)
   Getter returns:  163 (documented:  105 or  64%)
   Getter keys: 118 (documented:   89 or  75%)
   Getter values:  1133 (documented:  866 or  76%)
Setters:   814 (documented:  749 or  92%)
   Setter returns:   71 (documented:   45 or  63%)
   Setter keys:  57 (documented:   49 or  86%)
   Setter values:  1028 (documented:  776 or  75%)

=== TYPE SECTION: 1230 out of 1756 (70%) ===

Aliases:79 (documented:9 or  11%)
Structs:81 (documented:   57 or  70%)
Struct fields: 191 (documented:  156 or  82%)
Enums: 167 (documented:  151 or  90%)
Enum fields:  1238 (documented:  857 or  69%)

=== VARIABLE SECTION: 56 out of 56 (100%) ===

Constants:   0 (documented:0 or 100%)
Globals:56 (documented:   56 or 100%)

=== TOTAL: 7602 out of 9964 (76%) ===

regards
Stefan Schmidt

--
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel

Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-10-24 Thread Stefan Schmidt 
Hello.

On 24/10/16 11:27, Jean-Philippe André wrote:
> Hey Stefan,
>
> On 24 October 2016 at 17:27, Stefan Schmidt  wrote:
>>
>> [...]
>>> Also, I would argue that quite often an obvious parameter, getter return,
>>> etc... doesn't need to be documented, so the goal shouldn't be 100%
>>> coverage :)
>>
>> I expected that someone will bring this up. :)
>>
>> What is the real downside of doing it thought? It will cost you 2
>> seconds to write the doc for the return. Initially it will look obvious
>> and it might stay this way. It could also happen that some special
>> conditions need to be added. With the switch to a wiki based doc system
>> we also want to lower the barrier for users to contribute (on the wiki
>> side and not in the repo directly). Giving them the basic doc at hand to
>> edit and extent is important in my opinion.
>>
>> Even obvious parameters like len look a lot better being described as
>> "Length of the appended string" in the docs.
>>
>> A last, very selfish, argument is that giving out exceptions for some
>> cases makes it hard to track if we have all the needed other bits
>> documented (tooling can not make the decision here if somethign is so
>> obvious that it does not need a doc. That is even a different taste
>> between people. :))
>> 
>>
>
> In fact, it's a matter of choice. I agree with you as well (yes, I'm
> contradicting myself).
>
> Either the documentation generator duplicates the string or a human does it.
> I'm fine with either. Human-written doc can potentially look better but it
> means we'll have a lot of empty spots until we fill them in.

Sure, but we are not to bad. With 76% off all items covered. That is 
even for files that will not be part of our public API.

When we focus on the eo files meant as public API (removing non public 
eo files from install and running the generator on the installed files 
only) we wil have a reduced total number and, maybe, a higher documented 
level.

In any case I'm willing to bring this forward and will continue to work 
on the empty spots.

> As for stalling the documentation work, I believe the more you will expose
> those stats and doc pages, the more incentive we will have to remove
> excessive eo files and document those that need to be.

I hope so to :)

Maybe I should add them to the QA report each week. (and rename it to 
Stefan's weekly statistic newsletter. ;))

regards
Stefan Schmidt

--
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel

Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-10-24 Thread Jean-Philippe André 
Hey Stefan,

On 24 October 2016 at 17:27, Stefan Schmidt  wrote:
>
> [...]
> > Also, I would argue that quite often an obvious parameter, getter return,
> > etc... doesn't need to be documented, so the goal shouldn't be 100%
> > coverage :)
>
> I expected that someone will bring this up. :)
>
> What is the real downside of doing it thought? It will cost you 2
> seconds to write the doc for the return. Initially it will look obvious
> and it might stay this way. It could also happen that some special
> conditions need to be added. With the switch to a wiki based doc system
> we also want to lower the barrier for users to contribute (on the wiki
> side and not in the repo directly). Giving them the basic doc at hand to
> edit and extent is important in my opinion.
>
> Even obvious parameters like len look a lot better being described as
> "Length of the appended string" in the docs.
>
> A last, very selfish, argument is that giving out exceptions for some
> cases makes it hard to track if we have all the needed other bits
> documented (tooling can not make the decision here if somethign is so
> obvious that it does not need a doc. That is even a different taste
> between people. :))
> 
>

In fact, it's a matter of choice. I agree with you as well (yes, I'm
contradicting myself).

Either the documentation generator duplicates the string or a human does it.
I'm fine with either. Human-written doc can potentially look better but it
means we'll have a lot of empty spots until we fill them in.


As for stalling the documentation work, I believe the more you will expose
those stats and doc pages, the more incentive we will have to remove
excessive eo files and document those that need to be.


Best regards,

-- 
Jean-Philippe André
--
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel

Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-10-24 Thread Stefan Schmidt 
Hello.

On 24/10/16 05:15, Jean-Philippe André wrote:
> Hi Stefan,
>
> On 22 October 2016 at 07:43, Stefan Schmidt  wrote:
>
>> Hello.
>>
>> TL;DR: If you are committing new eo files I expect them to have full
>> docs from now one. Also help with the ones you are currently working on.
>>
>> Longer version:
>> If you look at the commit log you can see that I started another crusade
>> on getting our doc coverage for eo files.
>>
>> Right now we have the following stats for our documentation efforts:
>>
>> === CLASS SECTION: 269 out of 864 (31%) ===
>>
>> Classes:   255 (documented:   93 or  36%)
>> Interfaces: 57 (documented:   22 or  39%)
>> Mixins: 28 (documented:   28 or 100%)
>> Events:524 (documented:  126 or  24%)
>>
>> === FUNCTION SECTION: 6440 out of 7790 (83%) ===
>>
>> Methods:  1016 (documented:  936 or  92%)
>>Method params:  1667 (documented: 1401 or  84%)
>>Method returns:  493 (documented:  310 or  63%)
>> Getters:  1059 (documented:  970 or  92%)
>>Getter returns:  175 (documented:  105 or  60%)
>>Getter keys: 120 (documented:   89 or  74%)
>>Getter values:  1197 (documented:  924 or  77%)
>> Setters:   845 (documented:  779 or  92%)
>>Setter returns:   69 (documented:   43 or  62%)
>>Setter keys:  57 (documented:   49 or  86%)
>>Setter values:  1092 (documented:  834 or  76%)
>>
>> === TYPE SECTION: 1240 out of 1775 (70%) ===
>>
>> Aliases:84 (documented:9 or  11%)
>> Structs:82 (documented:   57 or  70%)
>> Struct fields: 191 (documented:  156 or  82%)
>> Enums: 170 (documented:  154 or  91%)
>> Enum fields:  1248 (documented:  864 or  69%)
>>
>> === VARIABLE SECTION: 56 out of 56 (100%) ===
>>
>> Constants:   0 (documented:0 or 100%)
>> Globals:56 (documented:   56 or 100%)
>>
>> === TOTAL: 8005 out of 10485 (76%) ===
>>
>> Which means we have 2480 undocumented items.
>>
>> I'm willing to work on this and I actually doing it already but if your
>> working area covers some eo files please make sure that you document all
>> bits in there. Some might look silly on a first glace (enums fields,
>> etc) but getting this to a 100% coverage, and keeping it, really helps
>> the doc efforts. We are using these to generate our documentation and
>> after some time for setup and migration of the older doxygen docs we
>> will switch to them. An example how they look like is here (design and
>> layout is up for suggestions but need to stay aligned with our www theme
>> to have a consistent look):
>> https://devs.enlightenment.org/~stefan/dokuwiki/doku.php?
>> id=docs:efl:auto:reference
>>
>> To keep track on the progress you can use:
>> src/bin/elua/elua src/scripts/elua/apps/gendoc.lua -src/lib/
>>
>> To get an output of what items are still need docs use the verbose flag:
>> src/bin/elua/elua src/scripts/elua/apps/gendoc.lua -v src/lib/
>
>
>
> Thanks for sharing this.
>
> One thing to note though is that a massive number of undocumented APIs are
> not meant to be part of our EO set of APIs. Either because they are not
> well (re)designed (eg. Ecore_Audio) or because they are meant to be
> internals (eg. Ector).

Yeah, I know. You brought this very valid point up once before and I did 
not forget about it. It leads to stalling the documentation effort 
thought. When you brouht it up I stopped the effort and thought I will 
wait until 1.18 is out and the current EO files are final. Didn't happen 
and we are still off by a good margin to come to this state. I feel I 
might even better keep going here and spent some later obsolete time on 
eo files instead of not working on it at all. :)

None the less your refresher is appreciated and I will try to keep the 
various areas in mind and focus on others.


  I'll try to remove some of the EO files from the
> install, step by step.

:)

> I assume gendoc.lua should be run against /share/eolian/include
> rather than the internal lib folder?

Well, with your effort to remove many of the unnecessary installed EO 
files this makes sense. So far it did not really make much of a 
difference thought and allowed for quicker testing (no need to make sure 
all old EO files are removed and installing the latest before running 
docgen)

> This unfortunately fails with "bad argument #2 to
> 'eolian_function_scope_get' (cannot convert 'nil' to 'unsigned int')".

Hmm, I will see if I can reproduce this. Maybe Daniel does know more.

> Also, I would argue that quite often an obvious parameter, getter return,
> etc... doesn't need to be documented, so the goal shouldn't be 100%
> coverage :)

I expected that someone

Re: [E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-10-23 Thread Jean-Philippe André 
Hi Stefan,

On 22 October 2016 at 07:43, Stefan Schmidt  wrote:

> Hello.
>
> TL;DR: If you are committing new eo files I expect them to have full
> docs from now one. Also help with the ones you are currently working on.
>
> Longer version:
> If you look at the commit log you can see that I started another crusade
> on getting our doc coverage for eo files.
>
> Right now we have the following stats for our documentation efforts:
>
> === CLASS SECTION: 269 out of 864 (31%) ===
>
> Classes:   255 (documented:   93 or  36%)
> Interfaces: 57 (documented:   22 or  39%)
> Mixins: 28 (documented:   28 or 100%)
> Events:524 (documented:  126 or  24%)
>
> === FUNCTION SECTION: 6440 out of 7790 (83%) ===
>
> Methods:  1016 (documented:  936 or  92%)
>Method params:  1667 (documented: 1401 or  84%)
>Method returns:  493 (documented:  310 or  63%)
> Getters:  1059 (documented:  970 or  92%)
>Getter returns:  175 (documented:  105 or  60%)
>Getter keys: 120 (documented:   89 or  74%)
>Getter values:  1197 (documented:  924 or  77%)
> Setters:   845 (documented:  779 or  92%)
>Setter returns:   69 (documented:   43 or  62%)
>Setter keys:  57 (documented:   49 or  86%)
>Setter values:  1092 (documented:  834 or  76%)
>
> === TYPE SECTION: 1240 out of 1775 (70%) ===
>
> Aliases:84 (documented:9 or  11%)
> Structs:82 (documented:   57 or  70%)
> Struct fields: 191 (documented:  156 or  82%)
> Enums: 170 (documented:  154 or  91%)
> Enum fields:  1248 (documented:  864 or  69%)
>
> === VARIABLE SECTION: 56 out of 56 (100%) ===
>
> Constants:   0 (documented:0 or 100%)
> Globals:56 (documented:   56 or 100%)
>
> === TOTAL: 8005 out of 10485 (76%) ===
>
> Which means we have 2480 undocumented items.
>
> I'm willing to work on this and I actually doing it already but if your
> working area covers some eo files please make sure that you document all
> bits in there. Some might look silly on a first glace (enums fields,
> etc) but getting this to a 100% coverage, and keeping it, really helps
> the doc efforts. We are using these to generate our documentation and
> after some time for setup and migration of the older doxygen docs we
> will switch to them. An example how they look like is here (design and
> layout is up for suggestions but need to stay aligned with our www theme
> to have a consistent look):
> https://devs.enlightenment.org/~stefan/dokuwiki/doku.php?
> id=docs:efl:auto:reference
>
> To keep track on the progress you can use:
> src/bin/elua/elua src/scripts/elua/apps/gendoc.lua -src/lib/
>
> To get an output of what items are still need docs use the verbose flag:
> src/bin/elua/elua src/scripts/elua/apps/gendoc.lua -v src/lib/



Thanks for sharing this.

One thing to note though is that a massive number of undocumented APIs are
not meant to be part of our EO set of APIs. Either because they are not
well (re)designed (eg. Ecore_Audio) or because they are meant to be
internals (eg. Ector). I'll try to remove some of the EO files from the
install, step by step.

I assume gendoc.lua should be run against /share/eolian/include
rather than the internal lib folder?
This unfortunately fails with "bad argument #2 to
'eolian_function_scope_get' (cannot convert 'nil' to 'unsigned int')".

Also, I would argue that quite often an obvious parameter, getter return,
etc... doesn't need to be documented, so the goal shouldn't be 100%
coverage :)

-- 
Jean-Philippe André
--
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel

[E-devel] Making documentation for all elements of a eo file mandatory for new files

2016-10-21 Thread Stefan Schmidt 
Hello.

TL;DR: If you are committing new eo files I expect them to have full 
docs from now one. Also help with the ones you are currently working on.

Longer version:
If you look at the commit log you can see that I started another crusade 
on getting our doc coverage for eo files.

Right now we have the following stats for our documentation efforts:

=== CLASS SECTION: 269 out of 864 (31%) ===

Classes:   255 (documented:   93 or  36%)
Interfaces: 57 (documented:   22 or  39%)
Mixins: 28 (documented:   28 or 100%)
Events:524 (documented:  126 or  24%)

=== FUNCTION SECTION: 6440 out of 7790 (83%) ===

Methods:  1016 (documented:  936 or  92%)
   Method params:  1667 (documented: 1401 or  84%)
   Method returns:  493 (documented:  310 or  63%)
Getters:  1059 (documented:  970 or  92%)
   Getter returns:  175 (documented:  105 or  60%)
   Getter keys: 120 (documented:   89 or  74%)
   Getter values:  1197 (documented:  924 or  77%)
Setters:   845 (documented:  779 or  92%)
   Setter returns:   69 (documented:   43 or  62%)
   Setter keys:  57 (documented:   49 or  86%)
   Setter values:  1092 (documented:  834 or  76%)

=== TYPE SECTION: 1240 out of 1775 (70%) ===

Aliases:84 (documented:9 or  11%)
Structs:82 (documented:   57 or  70%)
Struct fields: 191 (documented:  156 or  82%)
Enums: 170 (documented:  154 or  91%)
Enum fields:  1248 (documented:  864 or  69%)

=== VARIABLE SECTION: 56 out of 56 (100%) ===

Constants:   0 (documented:0 or 100%)
Globals:56 (documented:   56 or 100%)

=== TOTAL: 8005 out of 10485 (76%) ===

Which means we have 2480 undocumented items.

I'm willing to work on this and I actually doing it already but if your 
working area covers some eo files please make sure that you document all 
bits in there. Some might look silly on a first glace (enums fields, 
etc) but getting this to a 100% coverage, and keeping it, really helps 
the doc efforts. We are using these to generate our documentation and 
after some time for setup and migration of the older doxygen docs we 
will switch to them. An example how they look like is here (design and 
layout is up for suggestions but need to stay aligned with our www theme 
to have a consistent look):
https://devs.enlightenment.org/~stefan/dokuwiki/doku.php?id=docs:efl:auto:reference

To keep track on the progress you can use:
src/bin/elua/elua src/scripts/elua/apps/gendoc.lua -src/lib/

To get an output of what items are still need docs use the verbose flag:
src/bin/elua/elua src/scripts/elua/apps/gendoc.lua -v src/lib/

regards
Stefan Schmidt

--
Check out the vibrant tech community on one of the world's most 
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
___
enlightenment-devel mailing list
enlightenment-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/enlightenment-devel