Library standardization

[Jesse Phillips]

On Sun, 20 Apr 2008 22:18:33 +0300, Yigal Chripun wrote:

> Hans W. Uhlig wrote:
>> Jesse Phillips wrote:
>>> On Sun, 20 Apr 2008 12:27:51 +0200, e-t172 wrote:
>>>
>>>> Hans W. Uhlig a écrit :
>>>>> e-t172 wrote:
>>>>>> - More efficient. For example, on a Linux distro, if you want to
>>>>>> write a program using a library, you need to install the "dev"
>>>>>> package of the library, which only contains header files. There is
>>>>>> no point of including the implementation in the package, because it
>>>>>> is not useful to the user (and definitely not useful if you only
>>>>>> want to compile a project, not modify it). See the glibc as an
>>>>>> example : if you needed the entire source code of the glibc every
>>>>>> time you wanted to compile a program, this would have been a pure
>>>>>> waste in terms of disk space and compiler efficiency.
>>>>> Why should You need extra code files for development. I have always
>>>>> found this annoying, you either need the library or you don't. If
>>>>> the library has API documentation, why would you need headers.
>>>> Because API documentation is documentation, not D code that can be
>>>> parsed by a compiler. If I want to use a library, I have to write:
>>>>
>>>> import mylib;
>>>>
>>>> For that to work, you either need the header file "mylib.di" or the D
>>>> file "mylib.d".
>>>>
>>>>>> - Clear separation of "compiled" code and compile-time code. That
>>>>>> is, if a library provides "normal" code (accessed by an API) and
>>>>>> compile-time code (which is compiled in the application that uses
>>>>>> the library, not in the library itself), the two can be clearly
>>>>>> distinguished: "normal" code will only consist of declarations in
>>>>>> the header file, while compile-time code will be entirely defined
>>>>>> in the header file. That way, the user knows what IS in the library
>>>>>> (the .a or .so file), and what will be compiled in his application.
>>>>>> (of course this is already possible, just not as "clearly" for the
>>>>>> user)
>>>>> Ok, I can see this for fixed constants used by the library.
>>>>> Otherwise, why would you need them.
>>>> Huh? Sorry, I don't understand.
>>>>
>>>>>> - Ability to distribute closed-source libraries. I'm against
>>>>>> closed-source libraries, but I know that a lot of people need them.
>>>>> Again, I say API Docs!
>>>> See my first comment. There is no way API documentation can replace
>>>> header files. Unless, of course, you tell the compiler how to parse
>>>> and understand the API documentation, but that's just awkward.
>>>
>>> I'm sorry, but in reading through the posts I do not see how headers
>>> could replace API documentation. And here is the distinction I would
>>> like to put forth, what the programmer needs vs what the compiler
>>> needs. API documentation should be all you need to get information
>>> about the function you are calling. That is it for the user, they
>>> shouldn't need anything more, having a header file would just be
>>> redundant and not displayable on the web.
>>>
>>> Now there is the compiler. Many points for having header files have
>>> come up as they provide a means to compile library code without the
>>> source and other things. And it appears your view is that these header
>>> files should be created automatically. And all of this sounds exactly
>>> like the reasons for having di files. Which seems to have some
>>> problems, and it seems that it is a lot of speculation as to if it
>>> would be a problem or not. So my thoughts here would be: create
>>> examples as to would should be doable, show how it fails, and try to
>>> get di files fixed.
>> I agree. If the .di files can fill everything needed by the compiler
>> then they need not be human readable. api docs are for human
>> consumption .di are for compiler consumption
> 
> In a perfect world, you are right.
> however, not all programmers like writing documentation. what if the
> provided documentation is only partial? you've got a compiled lib and a
> .di file both not human readable as you propose. where do you get the
> API from?
> sometimes you need to look at the code and it helps if you only need to
> look at the header files that define the API and not all the code of the
> project which might be very large.
> 
> --Yigal

Yeah, so. The generated di files already do most of what is asked, sure 
it isn't very human readable and what ever other problems that come with 
inline code. If these files aren't doing enough, request correction in di 
generation, not an entirely new useless file.

Here are my thoughts on the lackluster readability of di files. For one, 
if your using a library with no documentation your liking going to have 
other problems than just the di files. 2nd you could request it be 
cleaned up. 3rd right a program to generate html that is human readable 
from the di files.