API Doc - You can help

Discussion in 'Developers' Forum' started by TonyG, Aug 18, 2020.

  1. TonyG

    TonyG Member

    New notes are getting added to the API documentation. The content.html page is getting a collection of FAQs that are common to all functions. Individual function pages will get notes as time and necessity seem to coincide.

    Please use this thread to comment on \remoting_client\API-docs, and to suggest new notes that you feel will be helpful to anyone using the API.

    This thread is about the text that explains how it works. We're talking about documentation here, not functionality.
    Please do Not use this thread to report other doc issues, to report API bugs or enhancements, or to ask questions about how the API works.

    If you have questions about the API, please create a new thread, get your info, and then post a note back here about how the doc can be enhanced for someone else with the same questions. As noted above, the doc notes includes FAQs that are found here in this forum - if a question is asked often enough, it may deserve a note in the doc. One-off misunderstandings and clarifications will probably not translate to a doc enhancement. Your patience and understanding is appreciated as this process continues.

    You should see the new content.html in v3.2. (And as a PR to v3.1-stable.)

    Thanks!
     
    Th0m and till like this.
  2. TonyG

    TonyG Member

    The first update of content.html was merged into stable-3.1. Please feel free to view and comment.

    From @till : "One note regarding error checking, the API uses the same error checks that the GUI is using in regard to entered field values. But it does not check relations of fields that are not available in the GUI."
    From @helmo "It would be nice to add some links to the function names such as system_config_get used in the text."

    Those notes and others posted here will be incorporated into updates. At some point I'll link to my fork/project so that anyone here can see progress and comment. Updates will not be posted quickly. I'm a total noob with ISPConfig, writing docs to help myself understand details as I learn them. Ref notes about blogging. I am not qualified to write authoritatively on details where I have no experience. But when I come to understand something about the API docs, in an area where I am interested, I'll update my version of the docs. When there is enough new material worth a contribution, I'll submit for merge. That's how FOSS works! :)

    But in areas where I am not using ISPConfig, changes may only occur based on notes in this thread. So again, YOU can help! For example, I may not update docs for functions related to DNS management, only because I don't understand how it works here yet. Until then, the more notes you folks contribute here about the DNS API, the more we can all learn how it works, and that information will get into the docs.

    Thanks all!
     
    Th0m, nhybgtvfr and ahrasis like this.

Share This Page