tillig / cr_documentor Goto Github PK

You can't use VSIX to install CR_Documentor because the installer metadata 
doesn't include VS11 as supported.

Thanks for creating this great plugin.

What version of the product are you using? On what operating system?
2.3.0.1 - Windows 7 64 bit

Please provide any additional information below.

Collapsing/Expanding documentation should be assignable to shorcut keys.

Documentation should be shown regardless of being in an XmlDocComment.  
ie.  If in a method that has doc, it should show the method's 
documentation.  Currently I don't keep the window open because it causes 
me to lose flow by having to move the cursor to the comments just to see 
the doc.  This is really bad especially if the documentation is not on 
screen.  I should just be able to see the documentation by being in the 
method.

Consider showing documentation for all members when not on a specific 
member.  This would be helpful because one could just look at the 
documentation instead of all the members of the class/struct/Interface...

Consider painting the formatted documentation in a compact form above the 
member like the sample CR_XmlDocCommentPainter that ships with CodeRush.  
The CodeRush one is nice but does not handle multi-formats within the 
details (like <code/>).  This should be available as an option or shortcut.

Again, GREAT product and thanks for your time,
Wil

Running VS2010, DXCore 2010.1 the context menu text helpers don't all
behave as expected.

--------------------
<para />, <code />:
(Both of these behave the same.)
Partial line selection/embedding doesn't work well in VS2008 or VS2010.
Remove it.

Full line embedding is inconsistent.
Select a full line and embed in <para />.
START WITH:
/// <summary>
/// Embed this.
/// </summary>

SELECT the entire "Embed this." line.

EXPECTED:
/// <summary>
/// <para>
/// Embed this.
/// </para>
/// </summary>

ACTUAL:
/// <summary>

/// <para>
/// Embed this.
/// </para>
/// </summary>


--------------------
Templates:
<list />, primary blocks (<param /> etc.):
START WITH:

/// <summary>
/// This is some text.
/// </summary>

Place the caret before "This" and insert a list template.

EXPECTED:
/// <summary>
/// <list type="definition">
/// <item>
/// <term></term>
/// <description></description>
/// </item>
/// </list>
/// This is some text.
/// </summary>

ACTUAL:
/// <summary>
/// /// <list type="definition">
/// <item>
/// <term></term>
/// <description></description>
/// </item>
/// </list>
/// This is some text.
/// </summary>

Now place the caret after "This" and before "is" and insert the template.

EXPECTED:
/// <summary>
/// This
/// <list type="definition">
/// <item>
/// <term></term>
/// <description></description>
/// </item>
/// </list>
/// is some text.
/// </summary>

ACTUAL:
/// <summary>
/// This /// <list type="definition">
/// <item>
/// <term></term>
/// <description></description>
/// </item>
/// </list>
/// is some text.
/// </summary>

In all cases, the "block" insertions appear to handle the first line of the
insertion incorrectly.


--------------------
Convert to XML Doc Comment:

The first line seems to be handled incorrectly.

START WITH:

[Required]
[DataType(DataType.Password)]
[DisplayName("Current password")]
public string OldPassword { get; set; }

Select it all, convert to XML doc comment.

EXPECTED:
/// [Required]
/// [DataType(DataType.Password)]
/// [DisplayName(&quot;Current password&quot;)]
/// public string OldPassword { get; set; }

ACTUAL:
[Required]/// 
/// [DataType(DataType.Password)]
/// [DisplayName(&quot;Current password&quot;)]
/// public string OldPassword { get; set; }

As users upgrade from one version of CR_Documentor to the next, the way 
settings are stored (the format) changes, the number and type of settings 
change... and if there's some reason for the user to roll back to a 
previous version of the product, the settings load/save is not robust 
enough to recover from a settings read error.

The way user preferences are stored and loaded needs to be updated so, at 
the very least, if an error occurs some default behavior will take effect.

Ideally as the application updates, old settings should be removed so 
settings disk space won't be wasted.

Should there be some sort of "panic button" that force-resets all of a 
user's settings?

Should settings store some sort of internal version so we can keep 
compatibility information? Doing that might allow us to say "If the 
current settings version doesn't match the plugin version, perform an 
upgrade or rollback operation to ensure the system behaves correctly."

What steps will reproduce the problem?
1. Installed CodeRush Xpress 10.2.4
2. Installed CR_Documentor 2.6. Using SandCastle style.
3. Started VS2008, loaded a C# project, and clicked on a XML documentation area 
in the code.

What is the expected output? What do you see instead?
Expected the documentation. Got the "Unhandled exception" VS dialog. After 
clicking "No" several times I would see the rendered documentation in the 
CR_Documentor window.

What version of the product are you using? On what operating system?
Window XP, CodeRush Xpress 10.2.4, CR_Documentor 2.6.

Please provide any additional information below.
Clicking "yes" to debug I would get to a script code in 
//localhost:11235/CR_Documentor/[some uuid]/ showing the exception coming from 
the "lfc.switchLanguage(..)" line:
        function setLanguage(value) {
            var names = value.split(' ');
            toggleVisibleLanguage(names[1]);
            lfc.switchLanguage(names[0]);
        }
The script code has a note indicating that it comes from SandCastle. Changing 
the preview style to NDoc 1.3 fixes the exception problem.

Regards,
Patricio.

What steps will reproduce the problem?

1. Enter a comment like this (Using UTF-8 with signature - Codepage 65001):
        /// <summary>
        /// Verarbeitung einer Änderung der Präsentation.
        /// </summary>

What is the expected output? What do you see instead?

The Documentor window will show this:
Verarbeitung einer Änderung der Präsentation.
It should show this:
Verarbeitung einer Änderung der Präsentation.


What version of the product are you using? On what operating system?
CR_Documentor 2.1.0.0 / Windows XP Professional SP3

Please provide any additional information below.

THX for this great tool! 

Once the internal web server is implemented, it needs to be augmented to 
support the ability to serve images and other files (CSS, JS) out of 
embedded resources. Particularly in Sandcastle preview, showing icons 
would make the preview much richer and more authentic.

Adding a VS package installer will allow us to participate in the Visual Studio 
extension gallery. It also means whenever an upgrade comes along, those folks 
who've installed through the gallery will get notified. NICE.

http://visualstudiogallery.msdn.microsoft.com/

There is an article about how to do this here:
http://www.skorkin.com/2011/10/deploying-dxcore-coderush-or-community-plug-ins-u
sing-a-vsix-extension/

Currently you can expand/collapse documentation blocks with a context 
menu, but there should also be an option to use a shortcut key for these 
actions.

What steps will reproduce the problem?
1. Open an instance of Visual Studio.
2. Open the CR_Documentor window.
3. Open a second instance of Visual Studio.
4. Attempt to open the CR_Documentor window.

What is the expected output? What do you see instead?
Expected - both instances of VS should show a CR_Documentor window 
correctly.
Got - only the first instance showed it.

The reason is that the first instance fires up the internal web server to 
listen to http://*:11235/ and when the second instance tries to start the 
web server, it fails because there's already a listener there.

One fix might be to listen on GUID-based subfolders, for example:
http://*:11235/eda90c96-69d5-4760-8c86-41fa9b1c39cb/
...instead of just the root path. You should be able to register multiple 
listeners on the same port differentiated by path. If each new instance of 
the documentor window generates a GUID and listens there, no clash should 
happen.

Consider painting the formatted documentation in a compact form above the 
member like the sample CR_XmlDocCommentPainter that ships with CodeRush.  
The CodeRush one is nice but does not handle multi-formats within the 
details (like <code/>).  This should be available as an option or shortcut.

The CR_Documentor context menu could use an icon next to it.

Being an Aussie it is confusing seeing 4/6/2009, although it would be nice 
to program a couple of months into the future and use it now, would make 
deadlines a thing of the past ;).

What I think would be cool is to have access to a format string and have 
the variables exposed.

So have a textbox labelled format string in the config, and have another 
label below it saying that {0} is the Initials, {1} is the fullname, {2} 
is todays date/time or something like that

This way someone can put in Task prefixs if they wanted. eg.

"'MODIFIED: {0} on {2:dd-MMM-yy HH:mm} -"

What you think?

What steps will reproduce the problem?
1. Installed CodeRush Xpress 10.2.4
2. Installed CR_Documentor 2.6
3. Started VS2010
4. Pressed Ctrl-Alt-Shift-O and clicked on the Tools Windows\Documentor page.

What is the expected output? What do you see instead?
Expected the Documentor options.
Got:
Message: Demand-loaded  (Tool Windows\Documentor) was not found after 
associated package load.

Options Path: Tool Windows\Documentor

Application/Object causing exception: DevExpress.CodeRush.Core
Method throwing exception: System.Type get_RealType()

Stack Trace...
   at DevExpress.CodeRush.Core.LoadOnDemandType.get_RealType()
   at DevExpress.CodeRush.Core.OptionsPageType.CreateInstance()

What version of the product are you using? On what operating system?
Window XP, CodeRush Xpress 10.2.4, CR_Documentor 2.6.

It would be nice to be able to click a little "pin" button on the preview 
window and have the preview stop refreshing. This way a user could 
navigate to some documentation, click "pin," then go somewhere else in the 
code and use the documentation as reference while they work.

If you view the class summary doc (the top level doc on a class or
interface) you also get a list of the class members in a three column table
(Icon, Member, and Description columns). The "Member" column shows the name
of the class member.

Right now, it ONLY shows the name, like:
GetCustomAttribute

It SHOULD show the name and any parameters (by type), like:
GetCustomAttribute<T>(String, Int32)

Create a sample enum, like:

using System;
using System.Runtime.Serialization;

namespace TestNamespace
{
  /// <summary>
  /// Test enumeration.
  /// </summary>
  public enum TestEnum
  {
    /// <summary>
    /// First member.
    /// </summary>
    MemberOne,

    /// <summary>
    /// Second member.
    /// </summary>
    [EnumMember]
    MemberTwo
}

Look at the class doc for the enumeration. In the table that lists the
members, the member without the attribute ("MemberOne") will have its
description correctly listed; the member with the attribute ("MemberTwo")
will not.

Both should have a proper description.

From the discussions on the VS Gallery: 
http://visualstudiogallery.msdn.microsoft.com/668a65b5-2468-4afa-b78d-8c369850e2
b2

"When VS2012 loads the plugin thrown an exception, I think it says something 
about a logging module or dll (I removed the plugin so I cannot tell you the 
exact text/message of the exception now)"

The latest release of DX breaks this excellent plug-in.

Any chance of getting an early fix?

Due to some shortcomings in DXCore 9.1.2, ProductModule implementations are
not properly registered from plugin assemblies. This was discovered during
the fix for Issue #17 - some changes in the way ProductModules are
implemented and registered occurred in the new DXCore.

CR_Documentor 2.3.0.0 released with a proper implementation of a
9.1.2-compatible ProductModule but the registration bit has not been fixed.
It has ostensibly been fixed in an intermediate build of DXCore and should
be available in 9.2.0/v2009.2.

This fix needs to be verified and if the "About" box functionality needs to
be tweaked so it works in v2009.2, do so.

The DevExpress issue for the ProductModule fix is here:
http://www.devexpress.com/Support/Center/p/B36747.aspx

The DevExpress issue where I asked for how to implement a ProductModule is
here:
http://www.devexpress.com/issue=Q202166

The Managed C++ or C++/CLI syntax representation isn't accurate.

For example:
   /// <summary>
   /// Gets the type of the stored class.
   /// </summary>
   property Type^ TargetType 
   {
      Type^ get();
   }

Which will show in the documentation preview as:
   property TargetType[]{   
      get; 
   }

Or:
   Int32 AddCmd(CIoDouble^ oCmdVal, String^ cmdName, Double dScale)
   {
      ...
   }

which displays as:
   public Int32 AddCmd(
      CIoDouble^^ oCmdVal,
      String^^ cmdName,
      Double^ dScale
   )

It looks like documentor doesn't yet have proper support for handling the 
hat operator and simply inserts one itself. Nor does ^ mean it can be used 
as an array, only * does in some situations. Documentor shouldn't alter 
the syntax as that would change the meaning of the declaration (in most 
cases).

I don't have experience with C++ with Managed extensions, so I don't know 
the behaviour in there.

What steps will reproduce the problem?
1. Install CR_Documentor 2.6.1 for Visual Studio 2008
2. Start Visual Studio 2008
3. Open a source file with comments

What is the expected output? What do you see instead?
When I click on a comment section in the source, Unhandled .NET exception 
dialog pops up.  I click continue and the comments are rendered normally in a 
tab.  The unhandled exception dialog shows up subsequently every time I click 
or change to a different comment section (figuring every time CR_Documentor 
renders)

What version of the product are you using? On what operating system?
CR_Documentor 2.6.1 on Visual Studio 2008 Pro/Windows XP Pro SP3

Please provide any additional information below.
Unhandled .NET exception dialog pops up with following information:

System.NullReferenceException: Object reference not set to an instance of an 
object.
   at CR_Documentor.Diagnostics.Logger.<>c__DisplayClass6.<InitializeLoggingDelegates>b__0(String message)

While the plugin appears to load properly, the tool window does not appear
when using DXCore v2009 vol 1.2.

What steps will reproduce the problem?
1. Create a VB project.
2. Add some XML documentation and include <see langword="null" />
3. Preview the documentation in CR_Documentor.

What is the expected output? What do you see instead?
Expect the <see langword="null" /> to render as "Nothing" in the VB
project; instead see "null" as if it were C#.

The reason for this is that the Sandcastle preview style uses
language-specific CSS to show/hide elements based on the selected language.
While the dropdown list indicating the language has been fixed to the
native document language (code language), the script that executes to
switch from C# to whatever language is not being executed.

The preview needs to be updated to either only include the
language-specific elements for the given document language OR the script to
change visibility needs to be executed.

Enhancement to deal with the KnownIssue 'The CR_Documentor window may not
update as "real-time" as you would expect.'

This is a feature that doesn't require immediate release but could be
included in the next 'feature-release'.

DXCore notifies the plugin if the text is changed, the plugin can trigger
an immediate reparse which would create the real-time effect desired.

Advantage is more immediate update during typing.
Disadvantage is increased processor usage, especially on larger files.
However to my knowledge, typing text causes part of a file to be
invalidated, the whole file or all files depending on the impact of the
change. I suspect a change in an XML comment isn't so severe the entire
tree needs to be reparsed.
I would recommend adding a timer to this feature, limiting this forced
update/reparse to twice a second. (500ms interval)
And possible side-effects should be explored as the parsing may effect the
user's editing experience.

Adding an option to allow the user to switch on this realtime behavior on
fast computers and switch it off on slower would get rid of yet another
'Known Issue'.

Code snippet (without timer):
this._events.TextChanged += new
DevExpress.CodeRush.Core.TextChangedEventHandler(this._events_TextChanged);

and

private void _events_TextChanged(TextChangedEventArgs ea)
{
   if (CodeRush.Source.InsideXMLDocComment)
      ea.TextDocument.ParseIfTextChanged();
}

Some changes in the way logging works cause CR_Documentor 2.6.1.0 to throw 
exceptions in DXCore 11.2.8.

While the released 3.0.0.0 version fixes these issues, it doesn't have 
compatibility with VS 2005 or 2008.

Can a one-time patch be issued to fix the problem just for those folks still on 
older VS?

Do something like this in a <remarks /> block:

<remarks>
You should see &lt;something /&gt; here.
</remarks>

When this renders, you won't see the word "something" inside the entity 
markings because they've been decoded and the browser is actually 
receiving them as literal < and > marks. They should be encoded before 
being displayed.

The top-level summary doc lists the members in a given class. Private members 
shouldn't be listed.

The port that the internal web server listens on right now is 11235. This 
should be a configuration option so advanced users can choose a different 
port that might work better for them, based on their system configuration 
and security settings.

This somewhat overlaps with Issue #10 - running CR_Documentor as a non-
admin.

BEFORE REPORTING A DEFECT please be sure you have installed the plugin
correctly (including UNBLOCKING the assembly) and have checked the Known
Issues wiki page for a solution to the problem. THANKS!


What steps will reproduce the problem?
1. Install DxCore 12.2.6 (the latest at time of writing)
2. Install CR_Documentor.vsix (containing CR_Documentor.dll file version 
3.1.0.1, the version in the Extensions Gallery at time of writing).
3. Launch visual studio and check the "DEVEXPRESS > Tools Windows" menu

What is the expected output? What do you see instead?
I expect to see Documentor but it's not there (this is not the "unblock" issue 
from the Known Issues page!).  I also expect to see CR_Documentor.dll in 
"%userprofile%\My Documents\DevExpress\IDE Tools\Community\PlugIns", but the 
directory is empty.

What version of the product are you using? On what operating system?
CR_Documentor.dll file version 3.1.0.1
DxCore 12.2.6

Please provide any additional information below.

Manually copying CR_Drocumentor.dll to the plugins directory makes it show up 
in the menu.

Using DXCore daily build 11.2.11.12102 the CR_Documentor context menu appears 
twice rather than the customary once.

Looking in the diagnostic log, you can see the settings getting updated twice 
and the context menu getting created twice.

Given the following documentation...

/// <summary>
/// <b>This is a test</b>
/// </summary>

The NDoc preview style will give the error "The given key was not present in 
the dictionary." This indicates the "unrecognized tag handling" is not 
functioning properly in NDoc preview style.

This has been verified in VS2010.

Currently MSDN is the default rendering engine - old-style NDoc. Since NDoc
has gone defunct and Sandcastle is supposedly the way forward, we should
make Sandcastle the default rendering style.

Right now the internal web server listens to * - any incoming host 
communication. Try listening to "localhost" specifically. This might allow 
us to take advantage of the hotfix outlined here:
http://support.microsoft.com/kb/939786/

It looks like the combination of the hotfix and us listening to localhost 
specifically will fix up the "Access Denied" issue. Try it out, see if the 
change affects functionality. If not, try to verify the access issue gets 
fixed. (Regardless, it's probably a good idea to be specific about the 
place we're listening, so if it works, leave it localhost.)

The internal web server has some MSTest unit tests that do actual serving 
of requests to verify things are functioning correctly. Occasionally, and 
on an unpredictable basis, these tests will hang and eventually the test 
request will time out.

Changing the build script to run MSTest.exe with the /noisolation flag 
seems to make them pass more often, but there's still the odd chance that 
it'll happen.

This hang does not happen if you run the tests from inside Visual Studio.

This could be related to the occasional report of the internal web server 
hanging when rendering previews. I've not yet been able to reproduce the 
web server hang while the plugin is running.

Logging currently is done by calling the static 
DevExpress.CodeRush.Diagnostics.ToolWindows.Log and 
DevExpress.CodeRush.Diagnostics.Menus.Log objects. It would be better if 
we could abstract ourselves away from that by logging to our own logger.

It looks like those static objects use the 
DevExpress.CodeRush.Diagnostics.LogObject under the covers and construct 
it by passing a string category corresponding to the namespace, like:

new LogObject("ToolWindows");

Can we create our own category?

The current mechanism that CR_Documentor uses to render the preview is by 
dynamically poking information into the IE DOM. This, combined with 
navigating to temporary pages on disk, causes the security warning to be 
issued when the preview window displays because the preview also uses 
JavaScript.

Unfortunately, this isn't something that can be reproduced on demand, but 
it is common enough that a reasonable amount of usage should display the 
behavior.

This should be fixable by implementing an embedded web server and serving 
the preview from there. That will make the IE control think it's really 
navigating to a web site and will put the content in a different security 
zone than "My Computer."

The first attempt at the embedded web server should be simple, like with 
HttpListener: http://www.paraesthesia.com/archive/2008/07/16/simplest-
embedded-web-server-ever-with-httplistener.aspx

Using the Sandcastle preview, the following...

/// <summary>
/// Summary here.
/// </summary>
public string PropName { get; set; }

...renders a syntax preview like this:

public string PropName[] { get; set; }

Tested under Visual Studio 2008 in C#. The incorrect brackets do not 
appear using the NDoc preview style.

When an enum is marked with [Flags], the table that describes the values 
renders differently than an enum that isn't marked with [Flags] (at least, 
in NDoc it does). The level of support for [Flags] needs to be evaluated 
and previews should correctly behave for enums with or without [Flags].

What steps will reproduce the problem?
1. Log on as a standard user in Vista
2. Run Visual Studio 2008 (but not with administrative privileges)
3. Open a .cs file
4. Right click on some XML documentation in the file
5. Select CR_Documentor > Show CR_Documentor Window

What is the expected output? What do you see instead?

CR_Documentor window does not appear. Nothing appears to happen at all.
Obviously, the window should appear as it does when running VS2008 as an 
administrator.

What version of the product are you using? On what operating system?

Windows Vista Business 32 bit, Visual Studio 2008, DXCore 3.0.8, 
CR_Documentor 2.1.0.0

Please provide any additional information below.

Can we please have an option in settings to disable the auto-refresh and have a 
refresh button in the toolbar and as a keybinding.

The reason behind is that sometimes Documentor slows down Visual Studio for me, 
especially after a few days of usage without restarting Visual Studio. Having 
Documentor paused at all times and just on when I need it helps with that and 
also makes typing in VS more responsive.

The VSIX info needs to be updated to support VS2013 and it needs to be tested.

There should be an option to show the rendered documentation regardless of 
if the caret is actually in the doc comment. For example, if in a method 
that has doc, it should show the method's documentation.

BEFORE REPORTING A DEFECT please be sure you have installed the plugin
correctly (including UNBLOCKING the assembly) and have checked the Known
Issues wiki page for a solution to the problem. THANKS!


What steps will reproduce the problem?
1.
2.
3.

What is the expected output? What do you see instead?


What version of the product are you using? On what operating system?


Please provide any additional information below.


From chat session with DevExpress:

Scott, it appears that CR_Documentor documentation should be updated 
accordingly. We no longer provide a separate DXCore download.