r195983 - Update the LeakSanitizer documentation with a proper link.

[Kostya Serebryany]

On Thu, Dec 5, 2013 at 12:15 AM, Sean Silva <silvas at purdue.edu> wrote:

>
>
>
> On Tue, Dec 3, 2013 at 11:03 PM, Kostya Serebryany <kcc at google.com> wrote:
>
>>
>>
>>
>> On Tue, Dec 3, 2013 at 10:00 PM, Sean Silva <silvas at purdue.edu> wrote:
>>
>>>
>>>
>>>
>>> On Mon, Dec 2, 2013 at 12:16 AM, Kostya Serebryany <kcc at google.com>wrote:
>>>
>>>>
>>>>
>>>>
>>>> On Sun, Dec 1, 2013 at 4:03 PM, Sergey Matveev <earthdok at google.com>wrote:
>>>>
>>>>> All sanitizer docs are hosted externally. I'm not really sure why,
>>>>> perhaps Kostya can say more about that.
>>>>>
>>>>
>>>> the sanitizer run-time is shared between clang and other compiler(s) --
>>>> today that's GCC, but we want to encourage other compilers to use our
>>>> run-time too.
>>>> So, we prefer to keep the docs in a single external place.
>>>> We do have some user documentation in docs/ though, don't we?
>>>> clang.llvm.org/docs/AddressSanitizer.html
>>>> clang.llvm.org/docs/MemorySanitizer.html
>>>> clang.llvm.org/docs/ThreadSanitize.html
>>>> clang.llvm.org/docs/LeakSanitizer.html
>>>>
>>>
>>> That's what I find strange. Shouldn't they be in one place? Why are
>>> there both external portions and internal portions?
>>>
>> What would you suggest?
>>
>
> I'm not sure. How much is there in docs/ that is not covered on the
> code.google.com wiki?
>
I hope none.


> or vice versa? It seems at least that the blacklist/specialcaselist format
> is documented in docs/ but not in the wiki,
>

It is described at
https://code.google.com/p/address-sanitizer/wiki/AddressSanitizer#Turning_off_instrumentation
Since it is clang-specific (gcc does not support it yet) the situation
makes some sense.
We also tend to not promote it widely -- most of the cases we've seen users
applying it -- they were wrong (suppressed real bugs thinking they were
false positives).



and there appears to be a ton of stuff in the wiki that is not in docs/.
>

Correct.


> Also the various sanitizer documentation appears to be strewn about 3
> different code.google.com projects.
>

Well, the tools *are* different.


> Maybe compiler-rt can grow its own docs/ to keep this all in one place?
>

But we still need some compiler-neutral place to keep the docs and this
will be the primary place we maintain.



> It's pretty easy to set up Sphinx (I did this for clang-tools-extra, for
> example); I'd be happy to help set that up for compiler-rt.
>
> I guess it ultimately boils down to where users should find the
> documentation. As a user of this feature, I would like to find complete
> user-level documentation for this feature (not "for more details, see...")
> among my compiler's docs. Sphinx's output is flexible enough that it should
> be able to integrate with other documentation systems if necessary (e.g. it
> has texinfo output which IIRC is what GCC's docs are written in).
>
> What was the rationale for introducing the duplication in the first place?
> (maybe it was me complaining about the lack of docs in-tree?).
>

We needed some minimal documentation in clang, but we don't want to
duplicate it completely (one copy will always be stale)
and we can not (nor want to) completely migrate to the clang docs.

I admit, the situation is not ideal.

--kcc


>
> -- Sean Silva
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20131205/70864fff/attachment.html>