Re: Required documentation (was: Documenting the C API)

Karl Millar
 

IMHO, we shouldn't consider tests to be part of the documentation.  That being said, having a common set of tests that can be used to check correctness / conformance would be a wonderful thing to have.


On Fri, Aug 5, 2016 at 8:53 AM, Lukas Stadler <lukas.stadler@...> wrote:
So proper documentation for functions could look something like this:
- short description
- extended description
- parameters (names, types, assumptions about them)
- return value (types, expected values)
- errors/longjmp (conditions under which this happens)
- gc behavior (can cause gc, under what conditions, implicitly protected arguments)

The tricky part, I think, is how much detail the description contains.
For Rf_findVarInFrame3, e.g., should the behavior wrt. environments with the “UserDefinedDatabase” class be documented?
Is that public API, or just private API for a specific package?
What if the user accidentally puts this class on an environment?

Functions and other definitions should also be grouped into categories, with appropriate documentation for each category.

Should we consider tests to be part of the documentation?
That is the only type of documentation that can be enforced, it could even be written in a vignette-like style.
(but that may be going a bit too far...)

- Lukas

> On 01 Aug 2016, at 23:54, luke-tierney@... wrote:
>
> There are three things beyond function name/variable name/function
> type that are important and can be hard to find:
>
> - might the function through an error or otherwise longjmp
> - might the function cause a GC
> - if so, which, if any, of the arguments are protected by the function
>
> Best,
>
> luke.
>
> On Fri, 29 Jul 2016, Vitek, Jan wrote:
>
>> There are some points that I can’t really speak to here. But there is
>> certainly value in documentation that can be automatically processed
>> by tools.  The doxygen format is indeed widely used.
>>
>> There are standards for documenting large projects, we don’t really
>> have to innovate in this respect. Why not adopt something that works?
>>
>> -j
>>
>>
>>
>>> On Jul 23, 2016, at 4:23 AM, Radford Neal <radford@...> wrote:
>>>
>>>> Based on the conversation around my patch, I think it's clear that we need
>>>> to understand what type of API documentation we'd like to have.
>>>>
>>>> My thinking is that doxygen-style comments in the header files are the
>>>> right way to go.  doxygen is the C/C++ version of the javadoc / roxygen
>>>> etc. family and is widely used.
>>>>
>>>> It puts clear documentation of the API right where most users will go to
>>>> look for it.  Being right there with the code, it's also _much_ more likely
>>>> to get updated when the code does than other formats.
>>>
>>> I'm not seeing the logic of this.
>>>
>>> First, it seems to presume that there is only one R implementation,
>>> but one of the reasons for this working group is that we don't expect
>>> that to be true.  Putting the documentation in _several_ header files,
>>> for the several implementations, certainly is not a recipe for easy
>>> maintanence of the documentation.  Are you assuming that a single
>>> header file will be usable without change by all implementations?
>>> That might turn out to be true, but I think there is also a good
>>> chance that implementations will need to do things differently (eg,
>>> make some facilities be macros rather than actual functions).
>>>
>>> Second, it presumes that the header file is "where most users will go
>>> to look" for doucmentation.  I don't think this is true for projects
>>> that have advanced to the point where users can read actual
>>> documentation, rather than having to scrounge information whereever
>>> they can.  Even the most rudimentary real documentation of an API
>>> function is going to contain all the information that's in the
>>> function prototype, so there's no point in a user also looking in the
>>> header file.
>>>
>>> Third, the conjunction of code and documentation is largely useless in
>>> this context, because the only code in the header file is the function
>>> prototype.  Most changes in specifications are going to involve what
>>> the function actually does, not just what the prototype is.  If you
>>> assume that maintainers aren't very good at keeping code and
>>> documentation in sync, I don't see why they would be good at keeping
>>> code in a .c file in sync with documentation in a .h file, especially
>>> when they aren't otherwise changing the .h file.
>>>
>>> Finally, you seem to be assuming that the documentation is terse and
>>> not very helpful, just giving the bare specifications of what the
>>> function does.  One might aspire to documentation that explains the
>>> rationale of the function, and when it might be useful, and gives
>>> several examples, with commentary on common errors.  But this is not
>>> the sort of thing that belongs as comments in the code implementing
>>> the function.  For one thing, it causes confusion with regard to
>>> source code control if there are constant changes to source files that
>>> are actually just tweaking the tutorial material and examples, with no
>>> change to what the function does or how it does it.
>>>
>>> I think there may be some confusion here between practices that may be
>>> good when writing a single program, and what is required when
>>> documenting an API, where the whole point is to document an interface
>>> that _isolates_ an application program from the implementation details
>>> of the functions defined in the API, because these implementation
>>> details are not fixed (and indeed exist in multiple versions).
>>>
>>>  Radford
>>> _______________________________________________
>>> Rconsortium-wg-api mailing list
>>> Rconsortium-wg-api@...consortium.org
>>> https://lists.r-consortium.org/mailman/listinfo/rconsortium-wg-api
>>
>> _______________________________________________
>> Rconsortium-wg-api mailing list
>> Rconsortium-wg-api@...consortium.org
>> https://lists.r-consortium.org/mailman/listinfo/rconsortium-wg-api
>
> --
> Luke Tierney
> Ralph E. Wareham Professor of Mathematical Sciences
> University of Iowa                  Phone:             319-335-3386
> Department of Statistics and        Fax:               319-335-3017
>   Actuarial Science
> 241 Schaeffer Hall                  email:   luke-tierney@...
> Iowa City, IA 52242                 WWW:  http://www.stat.uiowa.edu_______________________________________________
> Rconsortium-wg-api mailing list
> Rconsortium-wg-api@...consortium.org
> https://lists.r-consortium.org/mailman/listinfo/rconsortium-wg-api

_______________________________________________
Rconsortium-wg-api mailing list
Rconsortium-wg-api@...consortium.org
https://lists.r-consortium.org/mailman/listinfo/rconsortium-wg-api

Join Rconsortium-wg-api@lists.r-consortium.org to automatically receive all group messages.