Library standardization

[Yigal Chripun]

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