This thread looks to be a little on the old side and therefore may no longer be relevant. Please see if there is a newer thread on the subject and ensure you're using the most recent build of any software if your question regards a particular product.
This thread has been locked and is no longer accepting new posts, if you have a question regarding this topic please email us at support@mindscape.co.nz
|
Hi, We're going to use LightSpeed for our generating our data model. As part of this we want to include the C# style XML comments for all the cases and properties so it will be automatically included in our documentation. For the moment we have turned these off (by modifying base.vm), but this now produces a huge hole in the documentation Is it possible to have these added into the designer?
Craig |
|
|
|
|
We would be happy to add this feature but it's a bit larger in scope than one might think, so I'd like to see if we can subset what you need. In particular, do you require documentation for any of the following: * Value objects * Strong-typed LINQ unit of work * Entity views * Stored procedures * DTOs I am assuming that you will be requiring only a simple piece of text against each item (basically the <summary> element, no <remarks> etc. elements). Do you expect to supply the full rubric (e.g. "Gets or sets the spline reticulation retrogression.") or do you expect to just supply a description (e.g. "spline reticulation retrogression") and have the designer wrap this up with the usual MSDN-style formulas? The former gives you more control but the latter is probably less work for you (and may make it easier for us to repurpose the text into doc strings for value object constructor args, foreign key properties, etc.). |
|
|
|
|
At the moment interested in doc comments on the entities, plus their properties (both column and relationship properties) - the unit of work is makred as internal (modified the template) and other items are not used. Full control would be preferred - plus it would also be nice to have some of the other comment types (summary, remarks, example, exception and include). However I understand this is a lot of work Since you use NVelocity as the underlying engine, I could provide a provide a generic Comments class and modify the templates for you. You'd still need to add it to classes underlying $entity and $field, but this would reduce your work.
Craig |
|
|
|
|
We appreciate the offer and we may take you up on that -- thanks! However, the concern with multiple strings is not just around the effort but around clogging up the Properties window with doc-comment-related properties. So we'll need to do a bit of investigation into a suitable user interface before we can offer this level of control. (You probably don't want to be typing a code example or a lengthy Remarks section into one of those tiny text boxes anyway!) Did you have any particular thoughts/wishes on the UI -- I am currently thinking maybe a popup dialog... or perhaps even a whole new tool window... Aaugh, this is one of those areas where one really wishes one could just let people edit the doc comments in the text editor just like they normally would -- if only there were some way to let you write the comments in the partial class! |
|
|
|
|
Hi Ivan, I agree, trying to enter text into those little textboxes can be challenging (to put it mildly). There are the various UI editors, but they still seem to get in the way. Out of tool window/pop-up, I think the new tool window would be better. This could always stay open, making it much easier to read and enter documentation.
Craig |
|
|
|
|
Thanks for the feedback, Craig -- I'll get onto this. |
|
|
|
|
Hello Craig, Sorry this has taken longer than I expected, but there will be a preliminary release of this in the 24 June nightly build, available from about 1430 GMT. This will support only entities, entity properties and one-to-many associations (not one-to-one or through associations). The <summary> and <remarks> tags are built-in: if you need to enter additional tags such as <exception>, there is an "additional documentation" field where you can enter raw XML. To edit documentation, right click on the designer and choose Documentation. This brings up a tool window which tracks the selection. You mentioned you were using a custom template: please note that several of the default templates have been updated so you may need to merge the changes. As mentioned this is a preliminary drop and one of the purposes is to get feedback before doing any further work (whether on scope or on the UI). So please give it a go and let us know how you find it. |
|
|
|
|
Hi, Thanks for this useful new feature. Is it just me or is the summary box a little bit too small? If it were a scrollable box like the remarks box, it would be easier for me because I often have summaries that are more than a handful of words long. It is fine when the tool panel is floating or docked along a wide part of VS but I would prefer to keep it tucked out of the way in the bottom corner and in this location the remarks box is much easier to use than the summary box - which doesn't fit well with my usual documentation strategy. Thanks, Chris |
|
|
|
|
Sizing is a tricky one -- different people are likely to use summary and remarks in different ways (I usually make my summaries one-liners, and put all the details in the remarks section, but at least one other Mindscaper likes to put plenty of info in his summaries; de gustibus and all that), and a box that is too small when the window is docked in a corner may be too big when the window is docked across the bottom of VS. In the longer term, I guess this means we may need to make the boxes resizable and remember the sizes on a per-user basis. But that adds quite a bit of complexity, so it will have to wait until we have a bit more feedback and can gauge the range of usage scenarios! In the meantime, I've made the summary box a bit bigger (and scrollable) and the remarks box a bit smaller. The change will be in the 26 June nightly, available after about 1430 GMT. This probably still won't be a perfect fit for you, but hopefully enough for now! Thanks for taking the time to provide your feedback -- keep it coming! |
|
|
|
|
Hi Ivan, |
|
|
|
|
One other query - is it possible to set comments for the UnitOfWork that is generated? I've had a look around, but I can't find anywhere where the unit of work is exposed in the designer.
Craig |
|
|
|
|
Hi Craig, We de-prioritised doing the unit of work because we initially only did the items that you said you needed (I understood that you had marked the UOW as internal) -- for the same reason, some other objects (e.g. value objects, DTOs and one-to-one associations) don't yet support comments. We'll certainly get round to it but we wanted to gather feedback before putting in further work on the doc comments feature -- but if you do need this then we'll bring it forward. Thanks for the bug report on the delete button and for the suggestion about showing what's being edited -- we'll get these sorted for you! |
|
|
|
|
Hi Ivan, Yes, you are right, we had made this internal - I had forgotten to re-modify the template to set it as internal again. So, don't worry about the UnitOfWork.
Craig |
|
|
|
|
Thanks for the size changes. This does help and is certainly good enough to work with (not that customisable box sizes would be unappreciated, I just agree with you that they are not a high priority) Craig made a good suggestion regarding the difficulty of identifying which item you are working with. Following on from that, I notice that the LightSpeed model panel selection does not change when you select an item in the designer view. I thought that clicking through each item in the model list would be a useful way to add documentation to an existing model but I suppose that a link between the selected items in the model panel and the lsmodel diagram would be a pre-requisite for that to work. Any chance that this can happen or are there maybe some disadvantages to enabling a link between the diagram and model? Thanks, Chris |
|
|
|
|
Hi guys, I have now committed the following changes: 1. The documentation window now shows the name of the edited item. Unfortunately this does take up space -- I have not found a way of displaying it in the title bar without mucking up the tabbed display. 2. Delete key now deletes text instead of whole entities -- sorry about that! 3. Documentation window now tracks selection in the model explorer tree as well as on the diagram (so it should stay in sync with the Properties window). This required us to replace some toolkit code in favour of custom code: as far as I can tell this is all working correctly, but I may have introduced some funnies in the process, so please do let us know if you see anything awry. These will be included in the 30 June 2009 nightly build, available after about 1430 GMT. And thanks for the continuing feedback! |
|
|
|
|
Thanks for those improvements Ivan. I've used the feature for about an hour today and I've now got some lovely documentation on my model :-) One small thing I noticed is that there was a compilation error in the main model cs file after I had finished. This is because I put a new line in one of the remarks (I had two slightly separate remarks to make). The same problem occurs with the summary. The code in the cs file looks like this: /// <remarks>test1 I've just removed the new line now so no big problem but it would be nice if you could fix this one up eventually in case anyone else makes more extensive use of newlines in their documentation. Thanks, Chris |
|
|
|
|
This is now fixed and the fix will be in the 2 July nightly build. Thanks for letting us know about it! |
|
|
|
