Library standardization

[Hans W. Uhlig]

Jesse Phillips wrote:
> 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.

If indentation and such are such a problem, just run it through a pretty 
printer.

> 
> 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. 

Very much agreed

> 2nd you could request it be cleaned up. 

Again, Pretty printer

 > 3rd right a program to generate html that is human readable from the 
di files.

Why not make this part of the compiler.