RFC: API documentation (for 2017): making sure NVDA source code presents one of the greatest API docs out there

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

RFC: API documentation (for 2017): making sure NVDA source code presents one of the greatest API docs out there

Joseph Lee

Hi,

 

I’d like to request for comments before I proceed with further research into the following issue:

https://github.com/nvaccess/nvda/issues/6654

 

One of the advantages and weaknesses of NVDA source code (as it stands) is API docs. Although we do have development guide that gives high-level picture of what add-ons and other modules should do, more knowledge can be gained by reading NVDA Core source code. For those who’d like to go further than writing app modules, reading NVDA Core source code is a must, but because certain parts are not documented well, it is hard for some to get into NVDA Core development. One way we, the current NVDA developers can help, is writing down our know-how directly in NVDA Core source code, thereby allowing NVDA API docs to become one of the greatest out there and opening up opportunities for many to follow our footsteps by reading the improved documentation.

 

I do understand that NV Access may not have time or resources to pursue the task of adding or updating API docs. However, I believe that one of the best ways to showcase the power of NVDA is through extensive documentation, with our hard work, knowledge gained, and wisdom included in these pages. Documentation also serves as a valuable historical artifact – long after possible demise of NVDA, historians, generations of programmers and students can learn about history of the global movement that is NVDA and learn to appreciate our talents and mindset as they research further.

 

Because of time and effort involved, I’d like to suggest that we don’t use forceful advocacy to get this feature onboard right away – I’m thinking it is something we should try to do throughout 2017. Also, this is the kind of a project that those knowledgeable in the NVDA community (users, developers, observers, etc.) should take part in (NVDA source code is massive now), with one or two persons serving as overall coordinators and committing needed bits and recording names of contributors.

 

Thanks.

Cheers,

Joseph


------------------------------------------------------------------------------
Developer Access Program for Intel Xeon Phi Processors
Access to Intel Xeon Phi processor-based developer platforms.
With one year of Intel Parallel Studio XE.
Training and support from Colfax.
Order your platform today.http://sdm.link/intel
_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: API documentation (for 2017): making sure NVDA source code presents one of the greatest API docs out there

derek riemer

Hi:

This has been discussed before. If you are working on a piece of code, add doc strings. I would advise against just doing this in one big PR because it's a shot-gun surgery kind of and is the thing that causes merge conflicts all over the place. For example, Mick did a big refactor to browse mode the other day, and added some docstrings that weren't there. Doing it in this way makes for easier reviewing and is cleaner. If you point out and maybe put a list on the wikki however of the things that need docstrings, that might be useful.


On 12/20/2016 7:27 AM, Joseph Lee wrote:

Hi,

 

I’d like to request for comments before I proceed with further research into the following issue:

https://github.com/nvaccess/nvda/issues/6654

 

One of the advantages and weaknesses of NVDA source code (as it stands) is API docs. Although we do have development guide that gives high-level picture of what add-ons and other modules should do, more knowledge can be gained by reading NVDA Core source code. For those who’d like to go further than writing app modules, reading NVDA Core source code is a must, but because certain parts are not documented well, it is hard for some to get into NVDA Core development. One way we, the current NVDA developers can help, is writing down our know-how directly in NVDA Core source code, thereby allowing NVDA API docs to become one of the greatest out there and opening up opportunities for many to follow our footsteps by reading the improved documentation.

 

I do understand that NV Access may not have time or resources to pursue the task of adding or updating API docs. However, I believe that one of the best ways to showcase the power of NVDA is through extensive documentation, with our hard work, knowledge gained, and wisdom included in these pages. Documentation also serves as a valuable historical artifact – long after possible demise of NVDA, historians, generations of programmers and students can learn about history of the global movement that is NVDA and learn to appreciate our talents and mindset as they research further.

 

Because of time and effort involved, I’d like to suggest that we don’t use forceful advocacy to get this feature onboard right away – I’m thinking it is something we should try to do throughout 2017. Also, this is the kind of a project that those knowledgeable in the NVDA community (users, developers, observers, etc.) should take part in (NVDA source code is massive now), with one or two persons serving as overall coordinators and committing needed bits and recording names of contributors.

 

Thanks.

Cheers,

Joseph



------------------------------------------------------------------------------
Developer Access Program for Intel Xeon Phi Processors
Access to Intel Xeon Phi processor-based developer platforms.
With one year of Intel Parallel Studio XE.
Training and support from Colfax.
Order your platform today.http://sdm.link/intel


_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel

--

Derek Riemer

  • Department of computer science, third year undergraduate student.
  • Proud user of the NVDA screen reader.
  • Open source enthusiast.
  • Member of Bridge Cu
  • Avid skiier.

Websites:
Honors portfolio
Awesome little hand built weather app!

[hidden email]
Phone: (303) 906-2194


------------------------------------------------------------------------------
Developer Access Program for Intel Xeon Phi Processors
Access to Intel Xeon Phi processor-based developer platforms.
With one year of Intel Parallel Studio XE.
Training and support from Colfax.
Order your platform today.http://sdm.link/intel
_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: API documentation (for 2017): making sure NVDA source code presents one of the greatest API docs out there

Joseph Lee

Hi,

It won’t be a big PR – the role of coordinators is to go over the code with interested developers and divide the work, with each portion coming in as issue/PR pairs. At the moment I have identified at least two issues (to be filed as separate issues, referencing issue 6654), one of them being a simple oversight when MathPlayer work was done.

That brings up a question: now that we have projects in GitHub, could we utilize it now that we have related issues popping up here and there and group them under projects?

Thanks for your thoughts as always.

Cheers,

Joseph

 

From: derek riemer [mailto:[hidden email]]
Sent: Tuesday, December 20, 2016 10:29 AM
To: NVDA screen reader development <[hidden email]>
Subject: Re: [Nvda-devel] RFC: API documentation (for 2017): making sure NVDA source code presents one of the greatest API docs out there

 

Hi:

This has been discussed before. If you are working on a piece of code, add doc strings. I would advise against just doing this in one big PR because it's a shot-gun surgery kind of and is the thing that causes merge conflicts all over the place. For example, Mick did a big refactor to browse mode the other day, and added some docstrings that weren't there. Doing it in this way makes for easier reviewing and is cleaner. If you point out and maybe put a list on the wikki however of the things that need docstrings, that might be useful.

 

On 12/20/2016 7:27 AM, Joseph Lee wrote:

Hi,

 

I’d like to request for comments before I proceed with further research into the following issue:

https://github.com/nvaccess/nvda/issues/6654

 

One of the advantages and weaknesses of NVDA source code (as it stands) is API docs. Although we do have development guide that gives high-level picture of what add-ons and other modules should do, more knowledge can be gained by reading NVDA Core source code. For those who’d like to go further than writing app modules, reading NVDA Core source code is a must, but because certain parts are not documented well, it is hard for some to get into NVDA Core development. One way we, the current NVDA developers can help, is writing down our know-how directly in NVDA Core source code, thereby allowing NVDA API docs to become one of the greatest out there and opening up opportunities for many to follow our footsteps by reading the improved documentation.

 

I do understand that NV Access may not have time or resources to pursue the task of adding or updating API docs. However, I believe that one of the best ways to showcase the power of NVDA is through extensive documentation, with our hard work, knowledge gained, and wisdom included in these pages. Documentation also serves as a valuable historical artifact – long after possible demise of NVDA, historians, generations of programmers and students can learn about history of the global movement that is NVDA and learn to appreciate our talents and mindset as they research further.

 

Because of time and effort involved, I’d like to suggest that we don’t use forceful advocacy to get this feature onboard right away – I’m thinking it is something we should try to do throughout 2017. Also, this is the kind of a project that those knowledgeable in the NVDA community (users, developers, observers, etc.) should take part in (NVDA source code is massive now), with one or two persons serving as overall coordinators and committing needed bits and recording names of contributors.

 

Thanks.

Cheers,

Joseph




------------------------------------------------------------------------------
Developer Access Program for Intel Xeon Phi Processors
Access to Intel Xeon Phi processor-based developer platforms.
With one year of Intel Parallel Studio XE.
Training and support from Colfax.
Order your platform today.http://sdm.link/intel




_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel

 

--


Derek Riemer

  • Department of computer science, third year undergraduate student.
  • Proud user of the NVDA screen reader.
  • Open source enthusiast.
  • Member of Bridge Cu
  • Avid skiier.

Websites:
Honors portfolio
Awesome little hand built weather app!

[hidden email]
Phone: (303) 906-2194


------------------------------------------------------------------------------
Developer Access Program for Intel Xeon Phi Processors
Access to Intel Xeon Phi processor-based developer platforms.
With one year of Intel Parallel Studio XE.
Training and support from Colfax.
Order your platform today.http://sdm.link/intel
_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: API documentation (for 2017): making sure NVDA source code presents one of the greatest API docs out there

James Teh
Hi.
I don't think we need to think of these things as big community "projects". If you identify something that needs a docstring and you want to write it, submit a PR. If you are trying to reuse or work on something and you don't understand how something works due to poor documentation, file an issue so someone who knows the code can fix it. If you're working on some area of code and you see a missing docstring in the area, feel free to fix it as part of your work. Major code "audits" just aren't productive at this point, especially relative to other priorities.

Thanks.

Jamie


On Wed, Dec 21, 2016 at 4:48 AM, Joseph Lee <[hidden email]> wrote:

Hi,

It won’t be a big PR – the role of coordinators is to go over the code with interested developers and divide the work, with each portion coming in as issue/PR pairs. At the moment I have identified at least two issues (to be filed as separate issues, referencing issue 6654), one of them being a simple oversight when MathPlayer work was done.

That brings up a question: now that we have projects in GitHub, could we utilize it now that we have related issues popping up here and there and group them under projects?

Thanks for your thoughts as always.

Cheers,

Joseph

 

From: derek riemer [mailto:[hidden email]]
Sent: Tuesday, December 20, 2016 10:29 AM
To: NVDA screen reader development <[hidden email]>
Subject: Re: [Nvda-devel] RFC: API documentation (for 2017): making sure NVDA source code presents one of the greatest API docs out there

 

Hi:

This has been discussed before. If you are working on a piece of code, add doc strings. I would advise against just doing this in one big PR because it's a shot-gun surgery kind of and is the thing that causes merge conflicts all over the place. For example, Mick did a big refactor to browse mode the other day, and added some docstrings that weren't there. Doing it in this way makes for easier reviewing and is cleaner. If you point out and maybe put a list on the wikki however of the things that need docstrings, that might be useful.

 

On 12/20/2016 7:27 AM, Joseph Lee wrote:

Hi,

 

I’d like to request for comments before I proceed with further research into the following issue:

https://github.com/nvaccess/nvda/issues/6654

 

One of the advantages and weaknesses of NVDA source code (as it stands) is API docs. Although we do have development guide that gives high-level picture of what add-ons and other modules should do, more knowledge can be gained by reading NVDA Core source code. For those who’d like to go further than writing app modules, reading NVDA Core source code is a must, but because certain parts are not documented well, it is hard for some to get into NVDA Core development. One way we, the current NVDA developers can help, is writing down our know-how directly in NVDA Core source code, thereby allowing NVDA API docs to become one of the greatest out there and opening up opportunities for many to follow our footsteps by reading the improved documentation.

 

I do understand that NV Access may not have time or resources to pursue the task of adding or updating API docs. However, I believe that one of the best ways to showcase the power of NVDA is through extensive documentation, with our hard work, knowledge gained, and wisdom included in these pages. Documentation also serves as a valuable historical artifact – long after possible demise of NVDA, historians, generations of programmers and students can learn about history of the global movement that is NVDA and learn to appreciate our talents and mindset as they research further.

 

Because of time and effort involved, I’d like to suggest that we don’t use forceful advocacy to get this feature onboard right away – I’m thinking it is something we should try to do throughout 2017. Also, this is the kind of a project that those knowledgeable in the NVDA community (users, developers, observers, etc.) should take part in (NVDA source code is massive now), with one or two persons serving as overall coordinators and committing needed bits and recording names of contributors.

 

Thanks.

Cheers,

Joseph




------------------------------------------------------------------------------
Developer Access Program for Intel Xeon Phi Processors
Access to Intel Xeon Phi processor-based developer platforms.
With one year of Intel Parallel Studio XE.
Training and support from Colfax.
Order your platform today.http://sdm.link/intel




_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel

 

--


Derek Riemer

  • Department of computer science, third year undergraduate student.
  • Proud user of the NVDA screen reader.
  • Open source enthusiast.
  • Member of Bridge Cu
  • Avid skiier.

Websites:
Honors portfolio
Awesome little hand built weather app!

[hidden email]
Phone: <a href="tel:(303)%20906-2194" value="+13039062194" target="_blank">(303) 906-2194


------------------------------------------------------------------------------
Developer Access Program for Intel Xeon Phi Processors
Access to Intel Xeon Phi processor-based developer platforms.
With one year of Intel Parallel Studio XE.
Training and support from Colfax.
Order your platform today.http://sdm.link/intel
_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel



------------------------------------------------------------------------------
Developer Access Program for Intel Xeon Phi Processors
Access to Intel Xeon Phi processor-based developer platforms.
With one year of Intel Parallel Studio XE.
Training and support from Colfax.
Order your platform today.http://sdm.link/intel
_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: API documentation (for 2017): making sure NVDA source code presents one of the greatest API docs out there

Reef Turner
I'd love to extend Jamie's comment here. Catching missing or unclear
documentation during the review period is one of the best times. It's
very easy for people working closely to a change to write
documentation that assumes a similar level of familiarity. If you are
looking at a pull request, and notice that something isn't explained
well then go ahead and ask for some better in-code documentation.

On Wed, Dec 21, 2016 at 9:23 AM, James Teh <[hidden email]> wrote:

> Hi.
> I don't think we need to think of these things as big community "projects".
> If you identify something that needs a docstring and you want to write it,
> submit a PR. If you are trying to reuse or work on something and you don't
> understand how something works due to poor documentation, file an issue so
> someone who knows the code can fix it. If you're working on some area of
> code and you see a missing docstring in the area, feel free to fix it as
> part of your work. Major code "audits" just aren't productive at this point,
> especially relative to other priorities.
>
> Thanks.
>
> Jamie
>
>
> On Wed, Dec 21, 2016 at 4:48 AM, Joseph Lee <[hidden email]>
> wrote:
>>
>> Hi,
>>
>> It won’t be a big PR – the role of coordinators is to go over the code
>> with interested developers and divide the work, with each portion coming in
>> as issue/PR pairs. At the moment I have identified at least two issues (to
>> be filed as separate issues, referencing issue 6654), one of them being a
>> simple oversight when MathPlayer work was done.
>>
>> That brings up a question: now that we have projects in GitHub, could we
>> utilize it now that we have related issues popping up here and there and
>> group them under projects?
>>
>> Thanks for your thoughts as always.
>>
>> Cheers,
>>
>> Joseph
>>
>>
>>
>> From: derek riemer [mailto:[hidden email]]
>> Sent: Tuesday, December 20, 2016 10:29 AM
>> To: NVDA screen reader development <[hidden email]>
>> Subject: Re: [Nvda-devel] RFC: API documentation (for 2017): making sure
>> NVDA source code presents one of the greatest API docs out there
>>
>>
>>
>> Hi:
>>
>> This has been discussed before. If you are working on a piece of code, add
>> doc strings. I would advise against just doing this in one big PR because
>> it's a shot-gun surgery kind of and is the thing that causes merge conflicts
>> all over the place. For example, Mick did a big refactor to browse mode the
>> other day, and added some docstrings that weren't there. Doing it in this
>> way makes for easier reviewing and is cleaner. If you point out and maybe
>> put a list on the wikki however of the things that need docstrings, that
>> might be useful.
>>
>>
>>
>> On 12/20/2016 7:27 AM, Joseph Lee wrote:
>>
>> Hi,
>>
>>
>>
>> I’d like to request for comments before I proceed with further research
>> into the following issue:
>>
>> https://github.com/nvaccess/nvda/issues/6654
>>
>>
>>
>> One of the advantages and weaknesses of NVDA source code (as it stands) is
>> API docs. Although we do have development guide that gives high-level
>> picture of what add-ons and other modules should do, more knowledge can be
>> gained by reading NVDA Core source code. For those who’d like to go further
>> than writing app modules, reading NVDA Core source code is a must, but
>> because certain parts are not documented well, it is hard for some to get
>> into NVDA Core development. One way we, the current NVDA developers can
>> help, is writing down our know-how directly in NVDA Core source code,
>> thereby allowing NVDA API docs to become one of the greatest out there and
>> opening up opportunities for many to follow our footsteps by reading the
>> improved documentation.
>>
>>
>>
>> I do understand that NV Access may not have time or resources to pursue
>> the task of adding or updating API docs. However, I believe that one of the
>> best ways to showcase the power of NVDA is through extensive documentation,
>> with our hard work, knowledge gained, and wisdom included in these pages.
>> Documentation also serves as a valuable historical artifact – long after
>> possible demise of NVDA, historians, generations of programmers and students
>> can learn about history of the global movement that is NVDA and learn to
>> appreciate our talents and mindset as they research further.
>>
>>
>>
>> Because of time and effort involved, I’d like to suggest that we don’t use
>> forceful advocacy to get this feature onboard right away – I’m thinking it
>> is something we should try to do throughout 2017. Also, this is the kind of
>> a project that those knowledgeable in the NVDA community (users, developers,
>> observers, etc.) should take part in (NVDA source code is massive now), with
>> one or two persons serving as overall coordinators and committing needed
>> bits and recording names of contributors.
>>
>>
>>
>> Thanks.
>>
>> Cheers,
>>
>> Joseph
>>
>>
>>
>>
>>
>> ------------------------------------------------------------------------------
>>
>> Developer Access Program for Intel Xeon Phi Processors
>>
>> Access to Intel Xeon Phi processor-based developer platforms.
>>
>> With one year of Intel Parallel Studio XE.
>>
>> Training and support from Colfax.
>>
>> Order your platform today.http://sdm.link/intel
>>
>>
>>
>>
>> _______________________________________________
>>
>> Nvda-devel mailing list
>>
>> [hidden email]
>>
>> https://lists.sourceforge.net/lists/listinfo/nvda-devel
>>
>>
>>
>> --
>>
>> ________________________________
>>
>> Derek Riemer
>>
>> Department of computer science, third year undergraduate student.
>> Proud user of the NVDA screen reader.
>> Open source enthusiast.
>> Member of Bridge Cu
>> Avid skiier.
>>
>> Websites:
>> Honors portfolio
>> Awesome little hand built weather app!
>>
>> email me at [hidden email]
>> Phone: (303) 906-2194
>>
>>
>>
>> ------------------------------------------------------------------------------
>> Developer Access Program for Intel Xeon Phi Processors
>> Access to Intel Xeon Phi processor-based developer platforms.
>> With one year of Intel Parallel Studio XE.
>> Training and support from Colfax.
>> Order your platform today.http://sdm.link/intel
>> _______________________________________________
>> Nvda-devel mailing list
>> [hidden email]
>> https://lists.sourceforge.net/lists/listinfo/nvda-devel
>>
>
>
> ------------------------------------------------------------------------------
> Developer Access Program for Intel Xeon Phi Processors
> Access to Intel Xeon Phi processor-based developer platforms.
> With one year of Intel Parallel Studio XE.
> Training and support from Colfax.
> Order your platform today.http://sdm.link/intel
> _______________________________________________
> Nvda-devel mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/nvda-devel
>



--
Regards,
Reef Turner

------------------------------------------------------------------------------
Developer Access Program for Intel Xeon Phi Processors
Access to Intel Xeon Phi processor-based developer platforms.
With one year of Intel Parallel Studio XE.
Training and support from Colfax.
Order your platform today.http://sdm.link/intel
_______________________________________________
Nvda-devel mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/nvda-devel