[cfe-commits] r170260 - in /cfe/trunk/docs: AnalyzerRegions.rst analyzer/AnalyzerRegions.rst index.rst

[Sean Silva]

On Mon, Dec 17, 2012 at 4:08 PM, Ted Kremenek <kremenek at apple.com> wrote:
> We should just delete it.  Nobody is using it.  When we decide to properly document this, we can resuscitate the content from version control and bring it up to date.

Ok, I nuked it in r170401.


Jordan, somehow the message that Ted quoted didn't make it to me, so
I'll reply here:

> On Dec 17, 2012, at 9:28 AM, Jordan Rose <jordan_rose at apple.com> wrote:
> Sean, what do you think we should do with the analyzer docs in general?

I generally think that the documentation for a specific piece of code
should live in the same repository as the code itself. The rationale
is to guarantee that any developer working on the code has immediate
access to the documentation so that they can update it/add to it.

-- Sean Silva


On Mon, Dec 17, 2012 at 4:08 PM, Ted Kremenek <kremenek at apple.com> wrote:
> We should just delete it.  Nobody is using it.  When we decide to properly document this, we can resuscitate the content from version control and bring it up to date.
>
> On Dec 17, 2012, at 9:28 AM, Jordan Rose <jordan_rose at apple.com> wrote:
>
>> I don't know. It's fairly out of date, but wouldn't be too hard to bring up to date. However, it's an odd thing to have as the only analyzer internals documentation, and really none of the analyzer docs should live on the main Clang site anyway. (It's a downside of having the public docs be in docs rather than www/docs.) I'm not sure where we should put them instead, though.
>>
>> Ted, what do you think we should do with AnalyzerRegions.rst? Sean, what do you think we should do with the analyzer docs in general?
>> Jordan
>>
>>
>> On Dec 15, 2012, at 15:49 , Sean Silva <silvas at purdue.edu> wrote:
>>
>>> On Fri, Dec 14, 2012 at 7:36 PM, Jordan Rose <jordan_rose at apple.com> wrote:
>>>> --- cfe/trunk/docs/index.rst (original)
>>>> +++ cfe/trunk/docs/index.rst Fri Dec 14 18:36:53 2012
>>>> @@ -19,7 +19,6 @@
>>>>   ThreadSanitizer
>>>>   Tooling
>>>>   AddressSanitizer
>>>> -   AnalyzerRegions
>>>>   ClangPlugins
>>>>   ClangTools
>>>>   HowToSetupToolingForLLVM
>>>
>>> This doesn't remove it from the Sphinx docs build. However, it does
>>> cause a Sphinx warning that the document is not included in any
>>> toctree.
>>>
>>> Basically I see three options here.
>>>
>>> If the doc is so out of date that it will only confuse people, then either
>>> 1. bring it up to date (this is the "right thing" to do, which helps
>>> people who want to learn about the static analyzer), or
>>> 2. delete it (this doesn't help people understand the analyzer, but is
>>> at least better than leaving in a document which will confuse people).
>>>
>>> or, if the doc is out of date but still might be helpful, then
>>> 3. Leave it in the documentation (and fix the sphinx warning), but add
>>> a warning at the top (`.. warning::`) that informs the reader that the
>>> document is out of date but that it still might be helpful.
>>>
>>> -- Sean Silva
>>
>