Library standardization

[Hans W. Uhlig]

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?

Same place the DI file came from, Auto generated documentation like 
javadocs can provide the exact same information as a header file can 
plus add in any extra documentation that the programmer did provide.

so:
.d   - source file
.did - D interface Documentation
.di  - D interface "Header"
.do  - D object file (not sure what d uses as default. is it .obj?)

Each (group of) "source" file(s) should end up creating 3 files from it, 
Interface, Documentation and object


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

Why, Automatically generated documentation shouldn't be hard to create, 
I hate to say it but java did a good job in this respect even if their 
way about it needs to be upgraded.

> 
> --Yigal