DDoc adds filename as given on dmd command line in comment

[Jonathan M Davis]

On Wednesday, August 10, 2011 11:24:49 simendsjo wrote:
> On 10.08.2011 09:36, Jonathan M Davis wrote:
> > On Wednesday, August 10, 2011 09:13:02 simendsjo wrote:
> >> On 08.08.2011 15:36, simendsjo wrote:
> >>> I use absolute paths in a build script, and Ddoc uses the full path
> >>> in a comment in the generated files. This makes version control
> >>> very difficult as all developers has to use the same location (and
> >>> possibly operating system). Is there a way to avoid this without
> >>> changing by build script?
> >> 
> >> Could it instead just write the module? Or module as a filename?
> >> pack.mod ->  pack.mod
> >> or
> >> pack.mod ->  pack/mod.d
> > 
> > It probably could, but I don't know whether that's generally desirable
> > or not. I'm afraid that I don't even know what you're talking about
> > with regards to Ddoc using the full path in comments in the files
> > anyway. However, I wouldn't expect generated ddoc to be in version
> > control in the first place anymore than I'd expect generated binaries
> > to be in version control, so if that's the problem, I'd suggest that
> > you simply not put the generated ddoc in version control.
> > 
> > Regardless, if the current behavior is problematic for you, create an
> > enhancement request for it. I suspect that it's something that pretty
> > much no one has noticed - especially if it's something that's not
> > actually visible in the documentation when you view it.
> > 
> > - Jonathan M Davis
> 
> I add the generated documentation to github pages to have the hosted
> documentation somewhere. I could of course move it somewhere else, but I
> don't see why I shouldn't put it there.

Well, it's like a binary. It's completely regeneratable from the code, and 
it's generally just a waste of space to include it in a repo. Generally 
speaking, stuff which is completely generatable by build scripts isn't checked 
into a repository. Now, I can see why you'd want to do that with github, but 
generally, it's better to not include that sort of thing in a repo. Obviously 
it's up to you though.

> My generated ddoc:
>          <!-- Generated by Ddoc from c:\d\ext\dwin\index.dd -->
> 
> std.algorithm:
>      <!-- Generated by Ddoc from std/algorithm.d -->

I suspect most people reading the std.algorithm documentation wouldn't even 
think that that's a path. Though honestly, I'd discourage you from having 
absolute paths in a build script. I don't believe that that's generally 
considered to be good practice. It's not particular portable and is likely to 
cause issues for anyone else who wants to build the project.

So, I'd argue that this is only an issue, because you're doing some stuff that 
many people would argue that you shouldn't be doing, but I see no reason not 
to create an enhancement request about it. It seems a bit odd to me that Ddoc 
would be sticking the path in there anyway.

- Jonathan M Davis