[llvm-dev] Status of docs/BitCodeFormat.rst?

[Robinson, Paul via llvm-dev]

> -----Original Message-----
> From: llvm-dev [mailto:llvm-dev-bounces at lists.llvm.org] On Behalf Of Mehdi
> Amini via llvm-dev
> Sent: Thursday, October 13, 2016 10:51 AM
> To: Ismail Badawi (ibadawi)
> Cc: llvm-dev at lists.llvm.org
> Subject: Re: [llvm-dev] Status of docs/BitCodeFormat.rst?
> 
> 
> > On Oct 13, 2016, at 10:24 AM, Ismail Badawi (ibadawi) via llvm-dev
> <llvm-dev at lists.llvm.org> wrote:
> >
> > Hi folks,
> >
> > A while back I noticed some outdated information in
> docs/BitCodeFormat.rst about how parameter attributes were encoded — it
> describes an old encoding that was changed in 3.3 with the introduction of
> attribute groups. I opened a bug about this
> (https://llvm.org/bugs/show_bug.cgi?id=28941) and started trying to write
> a patch, but along the way ran into more and more issues (e.g. new things
> not documented, things that were removed or changed formats).
> >
> > So I’m wondering whether there is an interest in keeping this document
> up to date. I see that there are some commits to this file in 2016 so it’s
> not totally abandoned, but at the same time there is information that has
> been outdated for 5+ years.
> 
> We’re not very good at upgrading the documentation I guess.
> 
> > Assuming there is an interest
> 
> I think it is very valuable to document it though. Patches will be
> welcome!
> 
> > I’m also wondering whether (or how) to approach fixing this
> incrementally. For example, in trying to document the new paramattr
> format, I noticed that the type format is also outdated, and there is a
> conflict in block ids (i.e. the old TYPE_BLOCK format which is documented
> used blockid=10, but blockid=10 is now used for PARAMATTR_GROUP_BLOCK), so
> that fixing the paramattr docs on their own might introduce
> inconsistencies.
> > Would it be better to try & bring the whole document up to date at once,
> or would it be fine to do it incrementally & possibly introduce some
> strangeness in the intermediate steps?
> 
> Bitcode is supposed to be compatible since version 3.0.
> I’m not sure if we should just document the current state or keep track of
> the history.

In principle the docs captured by previous release branches would document
the history.  But if the docs have been wrong for a long time, then prior
releases don't document the format correctly.  Therefore I think we would
be better off describing the history in the "living" document.
--paulr

> 
> —
> Mehdi
> 
> 
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev