No header files?

[BCS]

Hello Yigal,

> On 27/10/2009 22:50, BCS wrote:
> 
>> And as soon as you *require* an IDE to view the stuff, working
>> without one goes from 'less than ideal' to functionally impossible. I
>> think we have been over this ground before; I have major issues with
>> tool chains that are more or less impossible to use without a
>> language aware IDE. I know there are productivity gains to be had
>> from IDEs and I know that even in the best of cases working without
>> one will cost something. What I'm saying is that I want it to be
>> *possible* to work without one.
>> 
> I'm not requiring anything of that sort. I view the metadata as
> machine readable information that is processed by tools like compilers
> and third party tools. The metadata is required to link in a binary
> lib file NOT as documentation of the interface.
> 

In theory yes. In practice....

If the meat data can be used for auto compleat then someone will make an 
IDE tool that does that. Once that happens the meta data can function as 
documentation and soon some people will start expecting people to use it 
as documentation. At that point it we functional be documentation. And now, 
even with the best of intentions, we are where I don't want to be. If it 
is possible to link a program without some human readable "documentation" 
you /will/ end up with libraries where the only documentation is non human 
readable.

>>> comparing to original source is useless - commercial companies may
>>> want to protect their commercial secrets and provide you with only a
>>> binary file and the bare minimum to use that file in your projects.
>>> D needs to support that option.
>>> 
>> I agree. What I want is that your "binary file and the bare minimum
>> to use that file" includes something with the public API that can be
>> handedly read with a text editor. (Really I'd like DMD to force
>> people it to include a proper well written documentation file with
>> good code examples and a nice tutorial but we all know that's not
>> going to happen).
>> 
> that handily readable something is documentation. NOT header files. If
> you really insist you can generate man pages or text files but for
> documentation MUST be easy to navigate such as click-able PDF, HTML,
> etc.
> look at this this way: a lib is a binary file with binary meta-data
> not
> ment for human beings. in order to know what API functions that lib
> provides you must provide documentation as described above and that's
> trivial to generate even without a single comment in the source.
> if you allow for header files that gives a reason for lazy programmers
> not to generate the documentation, even though it's as simple as
> adding
> a line in the makefile

Some fraction of libs will be shipped with the minimum needed to compile 
and link. If that doesn't include some form of documentation, some fraction 
of libs will ship without documentation. The point about trivially generateable 
is exactly the crux of the issue; it trivially generateable *with the right 
tools*. With the right tools (a good IDE) it's not no only trivial to generate 
but you don't even need to generate it. And now we are right back where I 
don;t want to be with a language that end up being nearly impossible to use 
without a pile of extra tools that are not otherwise needed. 
.
>>>> I'm cynical enough that I'd bet if D switches to a "smarter lib
>>>> format"
>>>> a lot of people would manage to forget the documentation.
>>>> With the current system, the library must be shipped with, at a
>>>> minimum,
>>>> a human readable list of prototypes.
>>> without proper documentation people will have no way to know how to
>>> use such libraries.
>>> 
>> If the lib is worth useing, the function names will tell you
>> something.
>> 
> and those function names would be provided in an easy to navigate and
> read HTML format. not in header files.

"What HTML file? The vendor didn't ship my PHB an HTML file."