Home

Atomineer User Manual - Atomineer Pro Documentation for

1. Each entry starts on a new line but can continue across several lines as can be seen for the exception description In this form however the comments are compact but many would find them quite hard to read While they can be used to generate external or Intellisense documentation they don t provide very human readable documentation in the source code We can improve the readability by adding extra features all of which are legal optional and a matter of personal preference for your team to decide upon e Use a consistent ordering of elements so readers can quickly find the information they need e Special lines separators can be used at the top and or bottom of the comment to visually delineate it from the surrounding code e Add whitespace to aid readability This can include o Blank lines within the comment to collect similar entries such as parameter descriptions into groups that are visually separated from other entries such as the summary or returns entries Blank lines between the comments and the surrounding code Extra whitespace between the entry tags commands e g brief and the description text o Extra whitespace indentation within the comment to create more readable text columns or blank lines to create paragraphs in long descriptions For example we could write the comments like this without affecting the quality or layout of any final external documentation but significantly i
2. name type Which produces a doc comment separator like this FindUserAccount Method Of course for Visual Basic the start of the separator must be or REM to make it a valid comment WE E HERE HERE ERR The clip separators option allows you to limit the width of the separator lines Normally as you indent a comment block the entire block moves to the right but this can make viewing or printing code more difficult To avoid this set the clip column for separators and they will be truncated at the chosen character column This option is usually combined with the Word Wrap Column option described below Choose the comment block style Line Prefixes Next you can set a prefix for every line within the comment For a multiline comment you can use any text within reason but for a block made of single line comments this should at a minimum start with the comment prefix or This allows you to create blocks such as this which has no line prefixes VES summary Finds a user account A Or this a line prefix of including several spaces to line the asterisk up with the top bottom separator lines summary Finds a user account Ty 23 For single line comment blocks it is necessary to start the prefix wi
3. nn If your command has a different name change the macro attribute as appropriate Now when you execute Add Doc Comment Atomineer should detect the legacy comment select the entire comment block execute your command code to pre process it and then parse and update the output of your command to finish the conversion process Itis recommended that when you have finished converting legacy comments you disable the pre processing Rule so that Atomineer no longer tries to execute your command the mechanism that must be used involves selecting the comment causing flickery redraws and executing the command can slow down comment processing quite significantly 79 Atomineer Menu Commands This section details the specific menu commands available to you Add Doc Comment Default hot key Ctrl Shift D This is the core command of the Atomineer Pro Documentation extension It creates or updates a Documentation Comment for any supported programming language Ct C CLI C C Visual Basic TypeScript Java JavaScript JScript PHP or UnrealScript It will create or parse and update any comments that conform to the configured Atomineer Style XML Documentation Doxygen JavaDoc or Qt formats with user customisable comment block separators top and bottom lines to delimit the doc comment and line prefixes Usage Place the cursor in an appropriate line e Anywhere in the first line of the file to generate rep
4. If you will use single line comments i e in C languages and in Visual Basic to form your doc comments you don t need top and bottom separators at all so you can set them to None if you wish You can also add any text you like within the comment separator lines so you can make separators like these I I ok o o Ek Eoo EE GER EE KE Eck eo A EG EE ee EK IKE ok kac o ok Io Kock E Eoo koe Ko d Eo E KE Ke ok oko eco ek ceo Eo oe e o KE E Copyright XYZ Corporation xf z2z2zz22z22z2z2z2zz22zz22 22 2z 22222 2222z222z222222222 2222 2222 222 22 22 2 2 2 EE zi 000 000 000 000 000 000 000 None HB BM HP BNBMIHHHPB MB Gg TATA LTT TTL TTT N PHP P B B MB C PHP M TTT B Bg LL GI M HIP Bg MTM P P CB P P B B BN M MP P P P B P ATTA AT AAT AAT TAA TAA TAA CB Cg T TB BGB M As long as it s a legal comment and can t be confused for a doc entry anything is allowed Atomineer also supports a multi line format for the top separator Just add n into the text anywhere that you wish to insert a newline So this format 2 2 n Copyright XYZ corporationin 22 Will produce a 3 line top separator like this Finally you can use type and name to add the type name of the code element into the top separator like this
5. endcode and verbatim endverbatim tags Note that these start end tags must be the first nonblank text on the line Documentation comments can include a mixture of XML and or HTML elements However you may also wish to use lt gt or amp characters in descriptions and code examples Atomineer will process the entry text converting these special characters into the entities amp lt amp gt and amp amp if necessary This feature can be disabled in the preferences if you do not wish to use the text in external documentation generation applications to keep the code 19 comments more readable In addition and gt characters within XML cref attributes will be converted to following Microsoft s documentation XML guidelines e f enabled the number of blank lines above and below the doc comment will be corrected to a user specified standard to help keep code files tidy The default is to enforce a single blank line above and below the comment The number of blank lines to enforce after region Hif public private protected can also be configured Deleted entries Any DocComment entries that are no longer required e g deleted parameters or exceptions no longer being thrown will be inserted at the end of the comment block with a prefix param name value gt This parameter has just been deleted lt param gt This approach preserves any text from these entries in case you wish to re use it
6. lt If isPointer y continue y desc null if it fails else gt If sName Clone Duplicate desc A copy of this object gt Will generate the description null if it fails else a copy of this object for a method called Clone that returns a pointer type or just A copy of this object if the method returns a reference type Note that Atomineer corrects the capitalisation to make the sentence structure correct Note that as these commands are executed in the order they are defined you must place more specific tests before less specific ones so that they match correctly lt IfNot gt command These work exactly the same way as If commands but the logic is reversed they only execute if all conditions evaluate to false Set command This command is unconditional It is always executed and simply sets one or more variables or the desc In most cases this is used for a catch all rule at the end of the rules script as you usually set an unconditional value for desc and processing then ends If name Equals gt If numArgs 1 desc Specific description for numArgs 1 case Set desc Catch all description for all other cases If However it can also be used to create and alter internal variables to change the outputs of following rules In this case you need to use the continue y attribute so that rules processing continues after the Set command as well as setting any variables needed For ex
7. lt summary gt amp J gt lt remarks gt user date lt remarks gt Js exception J gt param lt _ gt lt returns gt lt method gt 55 VM MB MM MIB TTL TTL lt summary gt An example method for documentation lt summary gt HH remarks Jason 12 3 2010 remarks II exception cref ExampleCodeException gt Thrown when we feel like it lt exception gt lt param cref firstParameter gt The first parameter lt param gt lt param cref secondParameter gt The second parameter lt param gt Hl returns The result returns dd dd dd When creating new comments Atomineer builds content for the most common entries for you The position of the following XML elements specifies where in the comment the entry or block of entries in the case of exception and param will be placed lt summary gt lt remarks gt exception lt param gt lt returns gt lt value gt When updating an existing comment Atomineer will re order the entries it finds to match the order given in the template ensuring consistency of commenting across your project s Any comment entries found that do not have a matching XML entry in the template will be deleted placed at the bottom of the comment marked with and then removed the next time you execute Add Doc Comment The special element lt _ gt adds a blank line between entries note that using th
8. If command see above to detect when attributes are applied to a method and add appropriate notes to the documentation 71 lt MethodReturns gt Rules used to generate the description for the return values for methods VB functions The following special variables can be used in this section mmethodTy per The type of the method one of method property indexer delegate eventhandler type The return type for the method const int i The return type for the method not including any modifiers int TiisFoDRUBFA y or n indicating if the variable type includes a or isREference y or n indicating if the parameter type includes an amp or ref lt WordExpansions gt and lt Prefixes gt This is a special set of rules that are executed to detect and expand abbreviations and remove prefixes They are called for each word in turn in a generated description in order to allow abbreviations to be expanded The desc that they generate should usually be given in lowercase to create tidy results For example lt If name ack desc acknowledge gt If name fg fore desc foreground gt To delete unwanted words such as library naming prefixes from documentation simply replace the word with desc to delete it from the final documentation That is a member like IpszUserName might be documented as the lpsz user name By removing the prefix lpsz this can be cleaned up to the user name T
9. _wordwrap false gt user date lt remarks gt 59 Adding TODO items to the Visual Studio Task List window You can add TODO HACK UNDONE entries to be displayed automatically in the Visual Studio Task Window However there are some limitations CH Visual Studio doesn t recognise task comments that directly follow an XML start tag so you must place the TODO on a blank line remarks TODO Don t forget to fill in the remarks remarks C Visual Studio ignores task comments inside DocXml blocks You must use the _verbatim true tag to emit a normal comment into the middle of the documentation block Note that the indentation used in your template XML is significant so you must set the indentation of the element s text carefully lt remarks _verbatim true gt TODO Don t forget to fill in the remarks lt remarks gt More Template Entry examples lt summary gt Place the summary first using Atomineer generated content SESCH comment Place remarks next containing the text No comment lt gt Add a blank line info author user gt Add custom entry info author Jason Williams gt author user lt author gt Add custom entry author Jason Williams lt author gt File Header and Footer Templates The file filefooter C C C and lt file vb gt filefooter vb Visual Basic templates are different from regular comment blocks because you aren t documenting a code el
10. this can be fixed by disabling certain minor features Let us know if you can t work out how to achieve your aims and we ll be happy to tell you if and how it can be done In a very high proportion of cases the answer is yes and the change needed is simple to apply 40 Key Coding Strategies Here are a few simple guidelines that you can follow to help Atomineer produce excellent results 1 Use descriptive naming Use brief but descriptive names for classes methods and variables so that Atomineer can extract useful descriptions from them as a solid basis for your own documentation text Consider which of these names gives you the clearest understanding of a variable s meaning n name userName nameOfTheCurrentUser Be consistent Using a consistent naming style makes it easy to set up good documentation rules for Atomineer You can add custom rules if for any bespoke conventions but by default Atomineer looks for industry standard and best practice patterns such as Naming conventions like SetXXX GetXXX CalcXXX ToString Equals Clone Serialize XXXFactory XXXProxy XXXException XXXEventArgs Use words and word ordering consistently e g Avoid mixing names like ItemCount Numltems TotalCount CountOfObjects that mean essentially the same thing settle on a convention and use it consistently Boolean properties parameters are made considerably clearer with the form IsXXX or AreXXX this distingui
11. My Documents Visual Studio 2033 Addins AtomineerUtils where the 20 indicates the latest version of Visual Studio installed up to 2013 The Extension will default to using My Documents Atomineer However if the Atomineer add in is installed it will instead share the add in s folder Using Different Settings for each Solution Project Normally Atomineer will use a single set of preferences to control its functionality but sometimes it is useful to be able to use different settings within each Visual Studio Solution or Project you are working on for example it is quite common in large companies to use a different header layouts and comment styles in different legacy codebases Atomineer allows you to set up different preference storage locations for each solution project as follows e Inthe Atomineer options switch to the General Settings tab e Inthe Preference Storage section enter the path s of your standardised folder locations using solutionPath or projectPath to represent the location of the project solution file e g solutionPath Resources AtomineerSettings From this point on Atomineer will search in your solution s Resources AtomineerSettings folder for its preferences customisations If they are not found there then it will continue to search in its default location To use this in a solution just set up Atomineer as needed for that solution and then copy your preferences into the solut
12. Vea cc VE val 7 gt Align XML element ends rec cn Lardy cc LAL val 149 gt cn Pitson cn Vea cn Lardy sreg sree Spec ccm PT val 12 j5 tcm VE val 7 gt cc LAL val 149 gt int a ant ibs 1 int sum Align to tidy up indentation int a int b int sum 89 Making the most of Alignment Arguably one of the best features of the Visual Studio editor is also one of its least known features Hold down Alt while dragging or use Alt Shift with the cursor keys and the selection becomes an arbitrary rectangular region column within the code These columns can be copied and pasted deleted and overtyped as you type the text is repeated into every line in the selection Once you have aligned the code into columns with Atomineer this feature makes editing tables of information incredibly fast and easy as you can move entire columns add and delete columns as easily as though you were editing a single line of text This feature is incredibly powerful once you get used to it and can save a huge amount of time Preferences When inserting whitespace either tabs or spaces will be inserted as defined by your Visual Studio preferences However there is one dedicated preference on the Other Features tab for this command When aligning code to a column it can be aligned to any column using spaces as necessary to minimise the inserted whitespace or to the next tab column using
13. anywhere else e g a renamed parameter and ensures you are aware that Atomineer thinks the text should be deleted If you execute the Doc Comment command a second time any such deleted lines will be automatically removed to save you having to manually clean up the comment Note that Atomineer can be configured to silently delete unneeded invalid entries in the Doc General tab of the Atomineer Options Additional tips e f you wish to re generate the auto doc text for any entry in your comment or the entire comment simply delete the entry comment and execute Add Doc Comment again to update it There is no need to delete the entire comment as Atomineer will automatically fill in any missing parts while preserving the others e Todocument exceptions that pass through your method from a called method i e uncaught exceptions document them as Passed when rather than Thrown when and the description will be preserved when Atomineer updates the comment Note The Atomineer variable except passprefix can be set to a different prefix to control the wording Atomineer uses to detect passed exceptions 20 Configuring Atomineer So how can we configure Atomineer to get the ideal comment format Set the Comment Format First decide on a comment format Xml Documentation JavaDoc or Qt This can be set on the Doc Style tab of the Atomineer Options Documentation Preferences Atomineer Pro dvar ormating Doc General
14. anywhere in a source code file you wish to process and execute the Delete Documentation from this File command Description When you execute this command Atomineer will process the active source code file removing any block documentation comments but not end of line comments that either use the C style languages or Visual Basic line prefixes or your configured Atomineer comment style This operation can be undone if you are unhappy with the result Important Notes e Please make absolutely sure that you wish to delete all documentation comments before confirming this action On completion review the results to ensure that Atomineer has only removed those comments that you intended It will preserve file header comments and non documentation comments but it is possible that it might remove something you did not intend You can undo to restore the previous state if you are unhappy with the results e Note that this command will remove comments that match your configured Atomineer documentation comment format If you use an unusual or nonstandard format it is possible that Atomineer might only partially remove some comments or may inadvertently remove non documentation comments Please review the results and discontinue use if your comment format causes side effects with this command 87 Align Code into Columns Default hot key sequence Ctrl Shift A Ctrl Shift C Quickly align text patterns into tidy columns and tables T
15. document This mode may fail when the Solution has not been successfully compiled or where Visual Studio itself does not provide the CodeElement information needed If this information is unavailable Atomineer will parse the code in the scope for itself searching for code elements to document This makes the command very useful in older versions of Visual Studio or when your project has not been recently compiled as it will succeed in conditions where the other Doc All In commands are unable to operate Document All in this File Project Solution Default hot key sequence Ctrl Shift A Ctrl Shift F These commands search one or more source code Files not C header files and apply the Add Doc Comment command to each major code element within them These commands are is only available for languages for which the required CodeElement Intellisense information is available i e it works best for net languages and in more recent versions of Visual Studio The commands are similar to Document all in This Scope but in files that contain several classes this will document everything in one pass 83 Usage Place the cursor anywhere in a source code file and execute the Document All in This File Project Solution command Note To document only the members of a single class at a time use the Doc All in Scope command instead Description When you execute the command Atomineer will search the Visual Studio Intelli
16. e g List int 67 pone Generates a complete see entry using the variable value as the content for the cref For example for a class called MyList lt T gt the variable 96containingClass AsSee 6 will expand to see cref MyList T gt Most of these commands are of little use on their own but once combined with Sentence e g Sentence SCase or Sentence L Case can produce much more useful or readable text output Special handling for better quality output The following special handling is provided to improve the quality of autodoc output These methods use heuristics to detect and correct the English which do not always succeed but do improve the output text in the majority of cases e Plural command can be used to attempt to pluralise a word as it is expanded e g Box gt Boxes e Anytext that has the word a in it is processed to replace the a with an or the so it is generally better to use a in preference to an or the in your rule description text Typical results of this are Report a warning Report an error Report the warnings Report the errors AutoDoc Section Documenting specific Code Elements Various types of code elements e g classes exceptions methods require different approaches for documenting them The AutoDoc section is thus divided into a number of type specific sections which are applied as appropriate to the item being documented These are described bel
17. event declaration In addition the following variables are available only for the Parameters section isout isOptional methodName numArgs lt Classes gt y or n indicating the parameter type includes an out y or n indicating if the parameter is optional The name of the method for which this is a parameter The total number of arguments for the method Rules used to generate the description for classes and structs The following special variables can be used in this section znumBases z baseNamex isStatic isPartial isSealed isAbstract isGeneric isTemplate The number of base classes interfaces this class inherits from implements Base class interface name where X is the 1 based index of the base e g baseName1 baseName2 y or n indicating if this class is static y or n indicating if this class is partial y or n indicating if this class is sealed y or n indicating if this class is abstract Iw or n indicating if this class is generic y or n indicating if this class is a template 70 lt Methods gt Rules used to generate the description for methods including VB subs and functions constructors destructors finalisers properties indexers delegates and event handlers The following special variables can be used in this section zmethodType zmethodName rawMethodName specialType retType retTypeBase nu
18. existing comments It ensures that comments conform to your and StyleCop s layout and style guidelines they contain valid XML Doxygen Qt JavaDoc and or HTML markup the documentation remains in sync with the code e g each parameter is documented listed in the order it appears in the method signature and documentation for any deleted parameter is removed the comments remain tidy and readable using word wrapping and by controlling the whitespace in and around them e Atomineer has many subtle optional features to improve your workflows These include Automatic comment extending When you type a column of text within a comment Atomineer will add the comment line headers and indentation for you on each new line so you can edit the text as easily as if the comment block around it was not there Hint Press return twice to break out of this mode If you paste code into a comment Atomineer will add comment line headers and indentation to enclose the pasted code as an example Automatic bullet point list extending as you type Start a line with an obvious bullet point e g 1 a and Atomineer will continue the bullets numbering on the next line Automatic entity conversions when updating comments Characters like lt amp gt can t be used in comments as they will break any XML or HTML markup in the comment Atomineer converts these to the correct form to be sure that your Intellisen
19. expressions compare the contents of the given variable with the comma separated list of values and return true or false if there is a match Note that the values to match can use the wild card in the same manner as If commands in the auto doc rules For example to suppress generation of an entry on methods that are overrides or static use _optional specialType override static Or to suppress generation of an entry for Test methods you could use _optional methodName Test If you use the Atomineer option to copy base class documentation to derived class methods entries in the base class will by default be copied to the derived class unless there is a matching entry already present However in some circumstances you may wish the derived class to not inherit the base documentation for that entry usually these are rare cases where you end up with both a generated entry and one duplicated from the base class In this case add _copyFromBase n to your template s entry to suppress the duplication of the entry from base class documentation In the case of auto generated entries such as param and exception the standard is to have no entries if there are no params exceptions to document However some companies require that an entry is retained as in lt param gt None lt param gt If you specify a_blankEntry this text will be used to create an entry in these circumstances _aliases details _punctuate false
20. follows and can contain other variables if required These can be edited in the Atomineer Options company copyright useremail property getonly property setonly property getset indexer getonly Your company s name Your company s copyright declaration Your contact email address Description prefix for a read only property Description prefix for a write only property Description prefix for a read write property Description prefix for a read only indexer 52 indexer setonly indexer getset z param optional zexcept passprefix true false Znul 18 nullptr stylecop docBasesWithSee docPrimaryBaseWithSee docOverridesWithSee docUseAttributes alwaysAddInForParams suppressInout Description prefix for a write only indexer Description prefix for a read write indexer Text prefixed to optional parameter descriptions When Atomineer sees an exception description it will normally remove it from the comment if it can t find a corresponding throw or code Contract in the method body By documenting an exception as Passed when you can indicate to Atomineer that the exception is not thrown directly within the method but from a subroutine that it calls This variable allows you to change the prefix normally pass that is used to detect this situation such as when you are not documenting in English The text used for doc
21. for quick and easy deployment of customisations across your entire team Defining Rules and Templates The rules fall into the following main groups which are described in more detail below e User Variables When generating documentaton comment text Atomineer can replace variable names such as user with context sensitive text This section allows you to add your own variables such as CompanyName e Templates Each template defines the comment block layout to use for a given type of code element allowing you to specify exactly what information is expected in the comments for e g methods properties and classes e AutoDoc rules These describe how to generate auto documentation for different code element types classes structs enums exceptions methods properties return codes parameters etc You can easily augment the default logic to add new automatic documentation based on the names and types relating to each code element to allow Atomineer to recognise and support the naming conventions you use 51 e Abbreviation expansions This section allows Atomineer to expand abbreviations to full English terms e g src gt source to produce more readable auto doc commenting e Replacements amp Acronyms This section is used when Atomineer is expanding a code element s name into a sentence format e g OpenTcpipConnection will be converted to open tcpip connection Each of these words is then looked up in the replaceme
22. formats It works just like the first option inserting nothing a space or tab or a new line after the entry text but before the end tag lt summary gt Finds the usellfaccount in the user database lt summary gt lt summary gt Finds the use ccount in the user database lt summary gt lt summary gt Finds the user ount in the user database lt summary gt lt summary gt Finds the useifffaccount in the user database lt summary gt 29 This combo box has one final option which inserts a newline but a so indents the end tag to line up with the text column like this lt summary gt Finds the user account in the user database lt summary gt Word Wrapping The check box at the bottom of this section controls word wrapping Atomineer can optionally word wrap the entry text to keep it tidy using a smart algorithm that tries to preserve indentation and formatting where it is needed but wraps plain text To disable word wrapping un tick the checkbox Word wrapping is applied at a character column by default 100 characters This can be an absolute position i e 100 characters from the left edge of the page or it can be relative to the start of the comment so that all comments are the same width regardless of their indentation e From left edge of page the comment will become shorter as it is indented deeper This is some text that is
23. g a library you may only want to document public protected members while leaving private internal members alone These options give you control over what Atomineer will document ccess level C VB Jav code elements M all 7 ang del ements Add Doc Comment Document Allin li only allow Gefoer R ete comments from other code el v commands When executing The first option controls whether the settings here apply just to the Doc All In commands or if you also want to affect Add Doc Comment as well The second selects the access levels for which documentation comments will be allowed all allows all members to be commented oublic protected would allow public internal methods but not private internal ones etc Note e If documentation is restricted then attempting to document an illegal code element will remove any existing documentation from it or ignore the attempt if it is not documented This can make it appear that Atomineer is not working if you do not realise why e This option is generally only available for languages that include the access level of each code element in its declaration C VB Java 36 Live Typing Aids Atomineer provides some special aids while you are typing within a comment or documentation comment block to help you to enter your comment faster These aids can be controlled in the Other Features tab o entities lt amp gt ga
24. it works best with net languages and in later versions of Visual Studio If this command cannot process your code try the Doc all in This Scope command as it uses Atomineer s own code parser to find the code elements to document This command will be greyed out if Intellisense information is unavailable but in some circumstances intellisense information can be incomplete in which case the command may report No code elements found to document or it may only document a subset of the code items present e For technical reasons relating to the way Intellisense information is returned by Visual Studio this command cannot be applied to C header files they will simply be ignored You must use Document all in this Scope on each file if you wish to generate documentation in headers 84 When documenting entire Projects or Solutions Note that processing hundreds or thousands of code elements in a single pass can be quite time consuming and requires Visual Studio to work hard possibly using a lot of memory Depending on the version of Visual Studio you may see code windows updating during processing This is normal behaviour In Visual Studio versions 2010 and 2012 the status line progress indicator can sometimes cease updating thus making it look as though the processing has locked up If this occurs status updates can sometimes be recovered by moving the main Visual Studio window This lack of feedback does not affect proce
25. optional alternate user defined style If found it will parse the comment so that it can preserve any existing documentation converting all of these formats to the user s configured style 2 Next Atomineer queries the Visual Studio Code Model Intellisense system Depending on the version of Visual Studio the programming language and whether the code has been compiled varying degrees of information will be available so Atomineer mostly uses this only to find descriptions that can be copied from existing documentation such as o For overrides copy descriptions from the base Class or Interface o For overloads copy descriptions from best match sibling overloads o Forall methods check if parameter documentation can be duplicated from other parameters properties or member variables in the class 3 Then Atomineer parses the text around the cursor position It picks out the elements that still need to be documented methods parameters exceptions etc and executes thousands of rules against them to automatically generate a description for them 4 In cases where Atomineer can t provide a specific description it uses a catch all such as expanding the name into a sentence form The intention is that typical documentation frequently includes this text so even though it may not seem like a useful initial description it is still a useful starting point that will hopefully save you a bit of typing So we can write code in a way tha
26. position and interprets it to decide how information derived from the last build of your to document it code C or is updated live as you type VB CH Pros Pros e Very tolerant of code errors even if e Provides comprehensive information the source code is incomplete or on code elements uncompilable Atomineer can often understand it and document it correctly Cons Cons e Only available when the code e Atomineer has no knowledge of your compiles has been compiled Often code beyond the few lines it is looking unavailable while typing new code asa at so does not know details about user result types macros etc e To be tolerant the parser makes e Users can disable intellisense making it educated guesses so can become unavailable confused and produce unexpected e Intellisense for C headers directs results if you find a case the parser Atomineer to the implementations in fails on please send it to us and we ll cpp files and often takes a long time do our best to fix it usually within 24 to fetch so intellisense cannot be used hours in C headers Atomineer Commands e Intellisense can be unreliable particularly in older versions of Visual Studio This problem is much less common from VS2013 onwards e Inthe original release RTM of Visual Studio 2015 some intellisense is unavailable due to unimplemented features in Roslyn causing Atomineer s Intellisense based commands to provide patchy coverag
27. possible this is controlled by the global option Keep short entries as a single line However if you wish to control this behaviour on a per entry basis you can add this attribute to force the entry to always use the multi line format This attribute would normally be applied to all summary templates giving more space by default to the summary but allowing returns to remain in the compact single line style true default If the word wrapping preference is enabled word wrap the text in this element false Ignore the preference and disable word wrap in this element true default Add punctuation at the end of the element if it does not appear to end in punctuation false Do not add any additional punctuation true Copy the text from this element verbatim no word wrap no punctuation no header on each line etc false default Format the text from this element using line headers and word wrap as configured true This entry is legal and should be formatted to the given position in the final documentation comment but should not be added by Atomineer if it is missing false default This entry should be added by Atomineer if it is not 58 _copyFromBase n _blankEntry text For example lt method gt lt remarks lt method gt present This attribute can also use a conditional expression of the form variable value1 value2 value3 or variable value1 value2 value3 These
28. private access suppressed Atomineer will document the property as if it only has a get 57 Special attributes for code element entries Special attributes can be added to control the handling of each documentation entry type individually These are differentiated from regular attributes by starting with an underscore character _tagName name _aliases name1 name2 _style multiline _wordwrap true _punctuate true _verbatim true optional false This is used to change the name of the documentation entry tag that is parsed and output by Atomineer For example Atomineer normally generates exception entries but some people prefer these to be called throws Adding exception _tagName throws to the template makes Atomineer output the entry using your preferred name This attribute contains a comma separated list of aliases for the tag for example exception _aliases throw throws When parsing existing comments Atomineer will then treat all of these names as aliases for the given entry type and they will be converted to the new name Note that it s not necessary to add the element tag or the tagName to the list of aliases i e use exception tagName throws aliases throw Rather than exception tagName throws aliases exception throws throw For standalone entries such as summary and returns by Atomineer can format the text as a single line entry if
29. saving modified o so before calling t Atomineer Documentation Viewer 3x IDocumentFactory CreateNewDoc Method Coa Q Exiting Socumert ioca tha der SR needs 15 alk the use abot mary malad 3x p Parameas Creates a new document deleting any existing document structure If the user interface needs to mull if it fails en he comme t saving modified documents it must do so before calling this method Atoemineer Documentation Viewer 3x To create an i e Z IDocumentFactory CreateNewTt Method use the follo P Crestes a new document deleting any existing di e IF the user interface needs to pe Type of the docu ask the user about saving modified documents it must efore calling this method PaintDocument Type Parameters text Thecommandc YP TDocType Type of the document torgetView The initial view Deck y Parameters TDocType CreateNewDoc lt null it fails or the new TO context he command context that this command is executing within May not be null targetView The initial view to link to the document Exceptions avalidArgumentExcept involidArgumentExceptian Thrown if the given context is nu Returns te and initialise Pal null if it fails or the new TDocType document ntDocument newDoc e new nul Examples exOoc Init ell To creste and initialise a Paint ent using this interface use the following code If you open the viewer it will automatically display any avail
30. types start to share common naming patterns Separate words in symbols Use camelCaseNaming PascalCaseNaming or underscored_naming to help Atomineer pick out the words in your names 41 6 C Avoid macros Atomineer only parses the code in the vicinity of the cursor and has no knowledge of the types and macros that may be defined elsewhere in your codebase C macros can be replaced with arbitrary text during pre processing and can thus confuse Atomineer and produce odd results Many uses of macros can be replaced by typedefs and templates However if necessary Atomineer can be configured with rules to correctly resolve custom macros that are used in your code 7 If Atomineer produces bad documentation for a feature of your code Check that the description has not simply been copied from an existing doc comment check the base class for overridden methods check the same class for overloads properties parameters and member variables Often Atomineer copies this documentation on the assumption that it is useful but if existing documentation is poor this strategy can backfire Consider if your naming approach could be more descriptive Perhaps try a couple of variations to see if Atomineer works better for slightly different patterns It is easy to add new documentation rules to handle cases that we haven t envisaged Generally the guidelines above are aligned with common programming best practices If someone has t
31. word wrapped at a particular column so that it forms an absolute boundary useful if the code will be printed out This is some text that is word wrapped at a particular column so that it forms an absolute boundary useful if the code will be printed out e From left edge of comment the comment will always be 100 characters wide regardless of indentation This is some text that is word wrapped at a particular column so that it forms an absolute boundary useful if the code will be printed out This is some text that is word wrapped at a particular column MM so that it forms an absolute boundary useful if the code will be printed out 30 Special case for short entries Finally there is a special case feature for short entries If the entire entry is short enough to fit onto a single line then all of the above rules can be optionally ignored and new formatting options are used These are a bit further down the same tab page jes line documentation entr a tab character In single try text insert Between the tag and the en a space character nd lt tag gt insert dthe e the entry text an E TTT Bew Lidd These options work exactly as described above but for single line entries only As they are for a single line entry you cannot insert newlines into them so the options are just none space tab Special Cases for Groups of Entries As described
32. you ve typed It s just doing as it has been instructed but unless you realise why the has just vanished it can be confusing When Atomineer can t produce specialised documentation for a code element it resorts to a catch all such as just repeating the name in sentence form i e param launchRocket gt launch rocket This may seem rather useless but if you think about how you would document this parameter true to launch the rocket immediately you will often find that Atomineer has saved you some typing If you don t like this behaviour the catch alls can be easily disabled in your rules Atomineer handles many languages and myriad code styles by parsing isolated snippets of text Occasionally a combination of syntax and personal coding style can cause this parser to become confused and produce odd results Send us any examples that exhibit such problems and we will do our best to improve Atomineer s code handling 46 Advanced Understanding Understanding how Atomineer generates documentation can help you to get better documentation out of it and also to understand why you might sometimes get unexpected results When you ask it to add a documentation comment Atomineer takes the following steps 1 First it looks at the text near the cursor position and parses it to see if it can find a documentation comment in any of 4 styles as configured by the user tripleslash slashstar and an
33. 1 1111111 111 1111 1111 111 1 1 1 1111111111111 lt summary gt ih Opens the database lt summary gt Add This option helps to keep the simplest comments compact and brief Note however that as soon as the description becomes verbose enough to occupy more than one line Atomineer will convert the comment into the regular multi line form when you update the comment The remaining options instruct Atomineer to go even further with member variable and enum entry comments and put the comment on the same line as the code element as an end of line comment Note This form is not supported by XML Documentation tools as they require the comment to precede the code element but this form of comment is compatible with Doxygen using a special markup For example a regular doc comment using Doxygen JavaDoc markup brief The maximum speed of this Vehicle double maxSpeed and the equivalent end of line comment double maxSpeed lt The maximum speed of this Vehicle The options allow you to set the comment start and end text so if you prefer you can use lt and to create a C style comment 26 double maxSpeed lt The maximum speed of this Vehicle A text column index can be set to force the comments towards the right This helps to form a tidy column of comments to the right of a block of variables double maxSpeed lt The maximum speed of thi
34. 97 assignments AddUser Arabella bunny AddUser Arabella bunny Align after commas AddUser John abc AddUser John abc AddUser Susanna password AddUser Susanna password Align before int values int values numbers 4379 81 4379 81 323692 1079233 323692 1079233 12 36846 12 36846 88 By applying the command several times left to right you can align multiple parts of the lines Align variable names Align assignments Align comments byte flags 0 options int volume 72 m3 long displacement 134 in water byte int long flags volume displacement 270 725 4 134 options m 3 in water case case case case Left t left break Top t top break Right t right break Bottom t bottom break Align after colons Align breaks case Left t left break case Top t top break case Right t right break case Bottom t bottom break The command will also align equivalent code elements such as logic operators work on non code text such as XML or CSV data and tidy up code indentation if readFile amp amp container IsEmpty amp amp file IsOpen reader null Align logic operators if readFile amp amp container IsEmpty amp amp file IsOpen Hl reader null grec cne Pitson cce PT val 12 gt e Align words rec cn
35. Atomineer Pro Documentation www AtomineerUtils com Nov 2015 Contents Introduction cieicedssssvcdesscucdassdeseedstssnceassiaveedesseacdassdevecsesssdcdassdaeecdessexecabodenendessedccas eden exes Seacdasedoses se 4 Important Background Information 4 Atomineer Commands Rte ae EFI acc ee ve he ERES 5 Other Atomineer Facilities eroe tr there eer e e ven A ieu eni tee erue 7 Installing Atormiifleer 6 0225 000a i ee orare en oan S Pra nea Co Cann e peas ea Sdedisancdseaien ddsdusiacceeiies IU n EARN S PE RERE 8 Backgro tid 5 ERE Me EEE E E 8 asea E ee ee ee Ee E ENEE ENEE EE Ee ENEE SEENEN 8 QUICK Setup E EE 9 Preferences and Customisations Location 9 Using Different Settings for each Solution Proiect eene 10 Multi user Installations 5 retrato teet eei ea eere ence ee C THER een a ed 10 Assigning Custom Hot Keys for Atomineer Commande 11 Unattended Command line Installation eee eee ceesseceecceceeeeeeaeeeeaceceeeeecsaeeeeaaeeeeaeeseaeesesaeeneaaeeeeees 12 Documenting with Atomineer ccccssssccccssssccccenssccccenssceccanssceccacssseccanssseccanssseccanssseseansssseeoaes 13 Documentation Comment Formats reete eroe e eR ne eee ia de e Ae erue a ee EA ER Ep eR eere ERES 13 Documentation Comments in Code eene enne enne enne enne nnne nnne nnne 15 Generating New doc rmientatlorn ee ertt ete m ve ete errat et ES 17 Updating existing documentation comments ccceesessececeeecesse
36. Doc A Welcome Doc Style DocF Add Doc Comment Line prefix AITA Bottom separator Note that setting this option may set some other preferences to common defaults so even though all affected options can be changed later this option should be chosen first Choose the comment block style Separators Next let s set the style of the border around our comment block the top and bottom separator lines and the prefix that goes onto each of the lines ion Preferences Atomineer Pro Documentation al Doc Advance e Doc Style Doc Formatting Doc Gener Welcom entation Xml Comment System eg DA Top separator Wii BS AAA ULL TS ee pim ator yr Bottom separ een eyon ip separators SO they do not extend bey These fields can be dropped down to choose from some common example options or you can just type any text you wish into them Atomineer doesn t impose many restrictions but you need to choose something that is compatible with the language you are using as well as any 3 party documentation extraction programs 21 If you wish to use C language multi line comments the top and bottom separators need to form the beginning and end of a valid comment block so at a minimum something like this is required vil Or even Hif false endif A common style fully supported by Visual Studio and Doxygen is to use a double asterisk at the start of the comment
37. Must not be null param autoCreate true to auto create an account if it is not found Heh exception InvalidArgumentException thrown if username is null empty eh contains spaces or is otherwise invalid AA returns 1 if the username is not found or p the database ID in the UserTable of the user s record AE Note here that the two param entries are not split by a blank line they form a group of the same type of entry so they remain together as a coherent block of entries The next option dictates whether all entries in the group are aligned to the same text column or if each entry is formatted independently i n Align all textin group to same colum s Add blank lines between blocks of entrie With the option disabled each entry is formatted on its own it maximises use of the available space but is hard to read Qparam username The login name of the user to find Must not be null param autoCreateIfMissing true to auto create an account if it is not found With the option enabled the entries are aligned with each other making the parameter list much easier to read but at the expense of using more space param username The login name of the user to find Must not be null param autoCreateIfMissing true to auto create an account if it is not found 32 Fine Tuning At this point you should now have a format that you re happy wit
38. Output window in the Atomineer Pro Documentation section Important Notes e Please see the notes on Doc All in this File above for details of the commenting operation of this command e Note that processing hundreds or thousands of code elements in a single pass can be quite time consuming and requires Visual Studio to work hard possibly using a lot of memory e Depending on the version of Visual Studio you may see code windows updating during processing This is normal behaviour e In Visual Studio versions 2010 onwards the status line progress indicator can sometimes cease updating thus making it look as though the processing has locked up If this occurs status updates can sometimes be recovered by moving the main Visual Studio window This lack of feedback does not affect processing which usually completes successfully in due course e Open files will be processed and left open and a new undo step will be generated for the changes made Non open files will be opened processed saved and closed no undo will be available in these files If you wish to review all the changes it is suggested that you check all work in to source control before executing this command so that the results can be easily diffed at leisure 86 Delete Documentation from this File This command deletes all documentation comments from the active source code file allowing the documentation to be regenerated from scratch Usage Place the cursor
39. able documentation for the nearest code element as the text cursor is navigated through your source code Please note that this feature is not currently available in C C header files nor for end of line comments The viewer handles common documentation mark up including basic HTML elements such as lt br gt lt p gt para c code b lt i gt lt strong gt h1 Right click anywhere in the viewer window to show options including e Select from a range of pre defined templates These change the documentation layout and fonts used to emulate different styles that can be produced by tools like Sandcastle Doxygen and JavaDoc e Scale all the text in the window to a size that suits your preferences Your choices will be automatically saved so that Atomineer uses the same options the next time you start Visual Studio 81 The viewer display will automatically reformat to suit the window size and can be resized and docked just like any other Visual Studio tool window Important notes e This feature is a text viewer rather than a WYSIWYG preview The formatting of the text will not match the output of external documentation generation applications or web browsers e The documentation shown in the viewer is only that contained within the documentation comment Atomineer will not augment it with other information such as lists of class members as the process of building this comprehensive documentation is time consum
40. above some documentation entries are standalone e g summary returns only occur once in any documentation comment while others may occur several times forming a group of similar entries e g if a method has 3 parameters there will be a group of 3 param entries The options we ve looked at so far only apply to the standalone entries Where a group is involved a separate set of rules are applied They work just as described above for the standalone entry options These also include a couple of extra options to enhance readability of the comment The first of these is to add blanks between groups blocks of entries lumn za Align all text in group to same colu k lines between plocks of entries M Add blan With this disabled the comment will look like this AE brief Finds a user account in the database param username The login name of the user to find Must not be null param autoCreate true to auto create an account if it is not found Qexception InvalidArgumentException thrown if username is null empty ih contains spaces or is otherwise invalid returns 1 if the username is not found or Hah the database ID in the UserTable of the user s record AE EN But with it enabled blank lines are inserted between the groups to aid readability AE brief Finds a user account in the database param username The login name of the user to find
41. add a header declaration for it Switch easily between C source and header files Hide Documentation Comments Uses Visual Studios Outlining mechanism to hide using Outlining documentation comments or attributes in a file Hide Attributes using Outlining Other Atomineer Facilities Atomineer also provides a number of other facilities that can help with documenting your code efficiently They include Documentation Viewer Documentation comments are often hard to read The viewer displays the current code element s documentation in a format similar to that on MSDN or as created by tools like Doxygen or SandCastle to make them easier to read Live Typing Aids These optional aids make it easier to enter documentation within comments o Automatically extend comments when you type Enter This allows you to continue O typing comment text until you are finished If your documentation block starts with a prefix character on every line e g and some indentation Atomineer will automatically insert this for you on each new line so you can type without having to worry about the block comment format that contains your description text Press Enter twice in a row to exit this mode Automatically continue bullet point lists in comments If you type a line starting with an obvious bullet point character or with a numerical id 1 2 3 a b c Atomineer can continue the bulleting numbering on each new line Improve
42. am name exampleParam gt An example parameter lt param gt returns true if it feels like it returns 1 11111111111111 11 1111 11 11 11111111111111111 1111111 11111 11 1 11 1 1 1 111 111111111111111 Note that the author and date are recognised tags and thus preserved in the resulting comment but if these are not set as legal entries in your templates they can be removed by simply executing the Add Doc Comment command a second time to update the new comment Note also that the remarks was not supplied so a new auto generated entry is added that records the author date of the conversion However as you can see Atomineer does the bulk of the conversion work for you Pre processing to help Atomineer Parse your Code You may find some cases in your codebase where Atomineer cannot convert your existing comments e g if they are in a special in house format or cannot parse your code correctly such as C code where in house macros are used within class method declarations To deal with these situations Atomineer provides several approaches that can be used to pre process the text of your source code before it is fed into Atomineer s parsing engine Regular Expression Replacements Occasionally Atomineer hits something that confuses it resulting in a lower quality of automatic documentation than expected Typical examples are when a typedef or define macro are used to represent special types in y
43. ample the following sets the isOptional variable to y If type optional gt Set isOptional y continue y eTE The text within the Set attributes can also use any variables and the processing commands that can be embedded within them Set upperName name UCase continue y 65 lt Execute gt command This acts like a subroutine call or a include it executes the given AutoDoc section and if it doesn t return a description continues execution at the command following the Execute lt Execute rules Variables gt Special abortComment option Atomineer can optionally only apply comments to code elements with given access levels This is usually used to stop documentation being generated for private members A special feature allows you to extend this do not document handling to any specific code element This is done simply by adding an attribute to an If IfNot or Set condition If access private abortComment yes gt If this attribute is hit while processing AddDocComment exits immediately without inserting a comment at all AutoDoc Section Using Variables Variables may be used as tests in If commands by using the varName test attributes described above Variables may also be embedded in the desc text to insert special text into the output Each variable is delimited by 96 characters use 9696 to insert a literal 96 symbol Any variable except ip can be used as many
44. an entire legacy comment in a form like this ZF CI e GR ode e EEE Kek ek k EEL EERE eeh Usage Open the datafile for reading Return Value true if the file was opened successfully Preconditions The filename must have been set in Init EE Notes and turn it into this 78 E RE REAM ERE EAE EEEE REE A E A AE eek brief Open the datafile for reading returns true if the file was opened successfully Preconditions The filename must have been set in Init EAEk AI EE E EE EE Nremarks This is now in a form Atomineer can parse and convert to whatever form you have configured If this does not match your block format you will need to set up an Alternate format see Automated Comment Conversion above so that Atomineer can recognise this partially converted comment In this example set the preference options to lt Alt Separator Values Ek dk dodo deiode ROIolokeoolor EL doloso oleo ELA RAE EAA EAE dok or RON gt lt Alt LineHeader value gt Alt SeparatorB Mal gt The last set up step is to tell Atomineer to execute your pre processing command whenever it is about to parse a comment Edit the Pre processing Rules in the Atomineer preferences go to the Doc Advanced tab and click the Pre processing button and uncomment the example entry ConvertComment macro Macros Atomineer Custom ConvertExistingComment gt
45. and match2 The If condition can also test if a variable is defined This is useful for determining if an indexed argument or meta data attribute is available for the current code element As above a comma separated list of variables can be tested and the condition will evaluate true if one or more of them are defined If defined argName3 desc This method has a 3rd Argument gt If defined attr conditional desc This method is marked Conditional If defined attr description attr information desc This has a Description or Information attribute gt If a string is matched Atomineer appends the text from the desc attribute if present to the output description This text can include variables which will be expanded for example lt If name Width desc The width of the containingClass s match If the If command has child elements these are then executed so if s can be nested to make the rules more efficient or achieve and logic If containingClass Rectangle Triangle Circle gt If name Area desc The area of the shape gt Tf 64 Normally when a match is made Atomineer will exit the script and use the description that has been built However by setting the attribute continue y you can instruct Atomineer to continue executing commands Any text you set in desc will be appended to allow several phrases to be concatenated to build a final output For example this
46. are often a hint to check the syntax of the surrounding code and if you find any problems to re document after the error is corrected Low information content Atomineer can only provide information that it can glean from the code The richer this information source the better it can do If a parameter is named n Atomineer will provide minimal documentation If it is userName Atomineer can do a much better job In some circumstances Atomineer copies description text from existing documentation This works on the theory that overridden methods will operate largely as their base class method does or that a parameter used throughout a class will have the same usage However if file name and user name parameters in a class are all called name Atomineer cannot distinguish them and so it can copy inappropriate documentation Unique naming not only helps Atomineer but also humans attempting to read the code If Atomineer finds existing documentation for a name it assumes that the existing documentation must be of good quality and it will duplicate it If this existing documentation is of poor quality or the name is overloaded with many unrelated meanings Atomineer s duplication mechanism can produce undesirable results 45 Some preferences can cause effects that can be confusing For example if you tell Atomineer not to document private methods and then you type in front of one Atomineer will delete the that
47. ation viewer live typing aids to improve editing in comments the ability to word wrap text in any comment block and some helpers for creating common code structures Atomineer supports a wide range of popular languages as well as many documentation comment formats and styles If the default Atomineer settings are not exactly as you require it can be easily configured to suit your needs and once set up you are unlikely to need to configure it again In addition to the more commonly used preference settings Atomineer provides a wealth of advanced options to help you fine tune Atomineer to your liking if you would like any assistance in adjusting these options just email us at support atomineerutils com and we will usually reply within 24 hours and do everything we can to help you Important Background Information When documenting Atomineer uses two mechanisms to find code elements to document and to understand those elements e Atomineer is able to parse the text of your source code e The built in intellisense code model information provided by Visual Studio These two approaches each have their own advantages and disadvantages and this should be borne in mind when using some Atomineer commands each command documented below includes details on how to get the best out if it Atomineer Parser Visual Studio Intellisense System The built in parser reads the text around the Visual Studio s built in intellisense system uses cursor
48. cal Documentation which stops Atomineer generating any descriptions at all it will only insert a see also entry that refers to the base class interface documentation Notes For description duplication to work well it is important that each name used in your class has a unique purpose or usage so that the description for each name in your code is unique Intellisense is a system built in to Visual Studio which Atomineer uses to duplicate description text Intellisense information is not always available so sometimes Atomineer may not be able to duplicate documentation as expected This is an effect of how Intellisense 34 works rather than a problem with Atomineer To get the best results use the most recent version of Visual Studio and make sure your code has compiled In general C and VB are well supported by Visual Studio C is supported but does not always work if the code has not been recently compiled Other languages Java may not be supported at all XML Documentation Options This section provides options for controlling the documentation that is output in XML documentation comments xmi Documentation Options documentation text Add Doc Comment Lu Generate StyleCop compatible e Generate StyleCop compatible text adjusts the way that some code elements e g constructors are described so that they follow Microsoft s StyleCop code analysis tool s description rules Doxygen JavaDoc Qt Documentation Options This se
49. ceenceceseceeeseeeesaeceeaaeseneeesaeceeaaeceeaaesnaeeseaaeeeeaaesnnnees 87 Align Code into Colu mins 3 notet t irte te teta tee ttd vaca cae do a utet e ated etn ineat 88 Create CH or C CLI Property c ccccscccsssccssscecssscecsseceeseecsseeecsaececssecesseecsaseeesaececseeceseeceaeeeeaaeceeseeens 91 Create C Access Methods t edente aie ege tea e e sehe RE ET Ada UR na DAE pare en 91 COPY ASH OX EE 93 Other Men Iteiis oci coi ec oe tee eee t ente n Ree m teet eR ae nh ER Y e eee Pn Rae Y e ER PR RE Re ve earn 93 Internal SuppressUI and AllowUl commande enne nnne nnn nnne nnne 94 Live Comment Editing Enhancements e ecce eee eese e eee eese enun eene KEEN ERRR KEEN EERR KEEN se sena soto sena sno 96 Deprecated Men Commands 1 ENER dE ee sp oon d po ooa eaa o ooa a Fe a cea Ee ao ENEE pn oria ena opas 98 Implement Declare C method 98 Open C C Source or Header 99 Hide Doc Comments using Outlining usesssesseseesesee eene ennemis nnne nnns nennen 100 Hide Attributes using Outlining esee nennen ennemis nnns an 100 Introduction Atomineer Pro Documentation is an addin extension for Visual Studio that aims to save a lot of time and effort when creating and updating documentation comments in source code As well as providing commands to create and update documentation comments for single code elements and across entire solutions it includes a document
50. cial return code W i W i W i W i W i W i W i int j lt summary gt Reads a named user option value from the UserOpts xml file lt summary gt param name categoryName gt The name of the category group containing the option lt param gt param name optionName gt The name of the option within the parent category lt param gt returns The option value always zero or positive or the built in default value for the named preference if it is not specified in the user s file lt returns gt ReadUserOption string categoryName string optionName Of course every programmer will have their own idea of how such a method should be implemented and will make assumptions about how such a method will work when they call it This is why we need documentation to clarify the details Documentation records and communicates key points of our design to others Why does Atomineer generate rubbish sometimes It can be frustrating trying to understand why Atomineer sometimes produces something unexpected Here are the top reasons why this can happen occasionally A syntax error in the code or documentation comment Atomineer always tries to produce a result and will usually do so even if you present it with bad syntax For example if a method does not have a closing so that it is not complete Atomineer can document exceptions that it finds in the following code So bad results
51. ction provides options for controlling the documentation that is output in Doxygen JavaDoc Qt documentation comments The Doxygen JavaDoc and Qt options are oc at Options C Add header references In ment Doxygen JavaD Add Doc Com e s brief tag AUTOBRIEF style to doc comments class of class entries oO Suppres a Add declarations prototypes e Suppress brief tag Normally the description is added as a brief or brief entry Qbrief Finds a user account in the database param userName The user s login name However in Auto Brief style any text without a tag at the top of the comment is automatically assumed to be the brief entry making the comment more readable Finds a user account in the database param userName The user s login name 35 e Doxygen will associate a documentation comment with the code that immediately follows it However you can optionally add the declaration of the code element in the comment For example fn FindUserAccount string userName e C Add header references will include header references when generating a class entry as in class Test class h inc class h Restricting Documentation by Access Levels By default Atomineer allows you to document any supported code element with the Add Doc Comment and Doc All In commands However if you are creating e
52. d delete key press behaviour in comments if you delete past the start of your description text Atomineer will automatically append your current line to the line above stripping out any intervening comment prefixes and indentation so you can type within a comment block s description column as if you were just typing plain text Tidy up code examples on paste If you copy code and paste it into a doc comment Atomineer will integrate it into the comment e g by adding appropriate comment prefix characters and indentation on every line Installing Atomineer Background Atomineer Pro Documentation is compatible with all versions of Visual Studio from VS 2005 to the current version as well as Atmel Studio 5 x and 6 x All editions of Visual Studio e g Community Standard Professional Premium Ultimate Enterprise VSTS are supported except for Express Editions which do not allow add ins to be installed Atomineer Pro Documentation was originally provided as a Visual Studio add in In more recent versions of Visual Studio add ins have been superseded by a new system called extensions As a result you have been provided with two Atomineer installers which have slightly different installation and uninstallation processes These installers apply to different versions of Visual Studio as follows Visual Studio 2005 2008 2010 Visual Studio 2015 onwards 2012 amp 2013 Atmel Studio 5 x amp 6 x AtomineerUt
53. d line for easier deployment to teams The options are AtomineerUtilsSetup exe i Install to the default location or upgrade an existing installation in place AtomineerUtilsSetup exe i lt folder path gt Install to the given folder path must be on the local hard drive and not in a protected location like Program Files This option should only be used for first time installs AtomineerUtilsSetup exe u Uninstall Please note e Installation Uninstallation will not proceed if Visual Studio is running e On Vista Win7 Win8 UAC will need to be disabled to avoid any UAC prompts stalling the unattended installation in this case the user will have to manually choose the yes option before the installation will complete Unattended installation of the Atomineer Extension can be achieved using Microsoft s VSIXInstaller exe utility VSIXInstaller exe is part of the Visual Studio installation and is usually installed to C Program Files x86 Microsoft Visual Studio 0 Common7 IDE where is the version of Visual Studio e g 14 for V82015 Installing From a command line execute VSIXInstaller exe q Atomineer Pro Documentation vsix Uninstalling From a command line execute VSIXInstaller exe q u 36d65faf 3b6c 4406 8de2 cfc91095da62 12 Documenting with Atomineer The menu commands provided by Atomineer are detailed later in this manual But first it will help to describe th
54. derstand and more memorable but that isn t documentation Documentation answers critical questions that users or maintainers of a class method will have like When is this method useful to me and how should I use it Can pass a null in this parameter lf the item is not found what will the return value be Why did you write this code to work in this way How is this class related to the classes over there Can you give me an example of how use this to connect to the remote server e Reading code takes time Good documentation summarises key knowledge clearly and concisely and doesn t include unnecessary details It s much quicker to work on well documented code because the knowledge you need is distilled into a concentrated form When writing a call to a method Visual Studio s Intellisense tooltips will show you the documentation live as you type without you having to find and read the code And if you start coding with a better understanding you will spend less time debugging to iron out all the little bugs and niggles and misunderstandings e Reading the source code requires a context switch from the calling site to the source code You have to open new windows and jump back and forth between documents Documentation can be popped up in a tooltip as and when you need it left open in a separate web browser window or sit on your desk in printed form e Methods are not often used in complete iso
55. dio to other applications it normally includes colour codes for the syntax colouring scheme This is not always very useful when you want to put the text into a document that will be printed or emailed especially if you use a non white background colour Additionally Visual Studio copies the text verbatim including all the indentation If you are just copying a code snippet this pushes your text to the right when pasted and any included Tab characters can cause the formatting to become a complete mess as few other programs treat Tabs as 4 spaces as Visual Studio does This command addresses these issues by copying the selected text in your document to the clipboard as plain text It optionally strips unnecessary indentation from the block and optionally converts tabs into spaces Note that for the text formatting to appear correct in the pasted text you must display it using a monospaced font e g Courier New or Consolas Other Menu Items 93 Atomineer Options Shows a dialog for setting the Atomineer Preferences Please see the Preferences section below for more information on setting up Atomineer Preferences Help and User Guide Opens the latest version of this User Guide page direct from the AtomineerUtils com website in your default Internet Browser PDF viewer Check for updates Accesses the AtomineerUtils com website to determine if a newer version is available for download Note This may be unable to co
56. e This problem should be resolved by future Visual Studio Updates Atomineer provides the following commands Command Add Doc Comment Document All In This Scope Document All In This File Document All In This Project Document All In This Solution Document All in Chosen Files Description Creates or updates the documentation comment for the code at the cursor position Documents all code elements within a given code scope e g file namespace class using the Atomineer Parser This is ideal for use in C headers where intellisense is unavailable when you want to document a small portion of a large file or when the other Document All commands fail e g when intellisense is unavailable These commands are shortcuts for common operations They all work the same way using the Visual Studio Intellisense system to find the code elements to process in a single file all files in a project or all files in a solution The underlying system used by the other Document All commands This command shows a user interface that allows you to select what you wish to document as well as additional options such as filtering files based on their filenames etc Delete Documentation in File Align Code into Columns Create a Managed Property or A C Accessor Copy As Text This command can also be used to create update or delete documentation throughout a selection of files This deletes all documentation com
57. e documenting facilities in more detail including e What documentation comments are and the formats they can be in e Using Atomineer to generate new documentation e How Atomineer updates existing documentation comments e How to configure Atomineer to best suit your needs e How to batch convert documentation from a legacy format Documentation Comment Formats First let s take a quick look at the basics What are documentation comments and what formats does Atomineer support A Documentation Comment is used to describe details of a code element such as a class interface method property or enumerated type The description serves two primary purposes 1 It can tell users of the code why when and how to use it call a method use a class etc 2 Itcan describe implementation details of the code to help us maintain it The basic details in a documentation comment can be provided by Self Documenting Code using descriptive names in the source code so that everything clearly describes what it is for This is a great start but there are many important details that can t be conveyed easily in self documenting code it typically tells you what a class or method is for but not why when and how to use it For example here is a descriptive self documenting method int FindUserAccount string userName It s obvious that it finds a user account based on a user s name But if we wish to use this method there are still
58. easy to parse Atomineer supports the following formats Format name Example entry param name userName gt XML Documentation The login name of the user to find param JavaDoc Doxygen param userName The login name of the user to find Ot Doxygen param userName The login name of the user to find 14 Here are some of the pros and cons of different formats Format name Pros XML Documentation Visual Studio will read XML docs and display them live in tooltips as you type calling code so you know everything you need to know about the method you are calling without having to stop typing to find and read its source code or external documentation Widely supported by popular documentation generation programs e g Sandcastle Doxygen However this format is the least human readable and the end tags increase the typing required to create the entries Doxygen Three of the most popular documentation systems for C style JavaDoc amp languages Ot Reasonably human readable Can be extremely compact and brief Unfortunately not supported by Intellisense As a result our recommendation especially for Visual Basic CH and C code would be to use XML Documentation this is supported by the most tools and the benefits of Intellisense which grow with every new Visual Studio release cannot be understated Documentation Comments in code In code documentation comments are usually embedded in co
59. eecsseeecsaececsseceeecesseeecsecesees 35 Restricting Documentation by Access Levels eene nnne nennt nsn nnn nra 36 Live Typing Aids ER ehm eei eiit a EN 37 Getting the Most out of Atomineer eeeeeee eese ee eese ee eene esent ense EE n sss to sess EE sess stone sensn 39 uge UL e oe EE 39 Key Coding Str tegies 21 oet ee une t de ea ion Unas 41 Self Documenting Code and Doc Comments 43 Why does Atomineer generate rubbish sometimes d 45 Advanced Understanding 47 Using Doc All in File versus Doc All in Scope nnnm nnne 48 Documentation Rules and Templates cssssscccssssccccssssceccenssccccanssseccacssseccansssescacssceseacssseseaaes 50 Custom Rules Files te rtt ta cte itt iicet out dnt le ette ee teet dnte 50 Defining Rules and Templates cccccccccccssssssscecececessessseseceeecesseseeaeeeceeseesseaaaeeeeeesseeseensaeeeeeesseesegs 51 UserVariabless Section 4 2 e Ree e deter deb ea Maeda ees 52 Templates Section er re o E ek lace e eR EEN XY ERN ERU YS EP CERE VES lets ANE 55 CUSTOM ElEMENES TIE 56 Variables ett AO REPRE a nen neha eee t eee 57 Special attributes for code element templates eene nnne 57 Special attributes for code element entree 58 Adding TODO items to the Visual Studio Task List window eeeeeeeeeennnern nnns 60 More Template Entry examples cesses nennen enne enne nennt inanis sns s rsen a danses ni nan 60 File Header and Footer Templa
60. eed in one short burst of documentation Just as a picture is worth a thousand words a good documentation comment can be worth a thousand lines of code The documentation comment is where we can gather and describe all these critically important details so that programmers who don t know every detail of the code other programmers and ourselves when we return to the code after several months working elsewhere can quickly and easily get to grips with the essential details needed to use or maintain the code We might describe these key features of the method like this FindUserAccount Summary Finds a user account in the database Parameter userName The login name of the user to find Must not be null empty Throws an InvalidArgumentException if username is null empty Exceptions j i contains spaces or is otherwise an invalid Windows Login name 1 if the username is not found or Returns the database ID in the UserTable of the user s record In order to make this information more useful we have separated it into several entries Each describes one specific part of the method making it easier for us to zone in on the important parts of the information This classification of the information also makes it easy for programs to pick through our documentation and build nicely formatted printable content out of it These programs typically require us to follow some formatting rules to make the content
61. eer describes this class in documentation as in Constructs a new instance of this class Options include the classname with or without namespace e Add author entries and Add date entries control whether the author s name and or date are added to every generated comment In DocXML these are both added to the remarks entry un tick both options to stop the remarks entry being generated at all while in Doxygen formats they generate separate author and date entries e When updating a comment if Atomineer finds a doc entry such as a param entry for a parameter that is no longer present in the code or a custom entry that is not defined in the Atomineer Templates it will consider it invalid and remove it in one of two ways Delete the invalid entry immediately Mark the entry with a prefix like this 33 param cref missingParam gt This parameter is missing lt param gt If you update the comment a second time Atomineer will then remove the marked entry This allows you to see what you will lose when updating giving you a chance to rescue any description text that you realise you still want to use somewhere else in the comment Note that Atomineer considers the most common documentation entries valid by default and any entries that are not in this list will be removed If you wish to use additional entry types you will need to add custom entries to your documenta
62. ement Atomineer offers two options 1 If this template includes any embedded XML elements it will be treated as a regular Documentation XML comment and will thus take on the separators and other style configured for your comments 2 If there are no embedded XML elements this template is treated as a block of freeform text WYSIWYG 60 In both cases you can insert any of the global variables in the table above or the following special file header variables ANE at Description of this file as generated by the lt File gt autodoc rules see below Below are examples of different styles of file comment that you may find useful Default plain text Atomineer header for C C C lt file gt file projectpathname tt summary 4fileDescription lt file gt Default plain text Atomineer header for Visual Basic lt file vb _separators false gt file projectpathname summary 4fileDescription file vb Free form text This template simply contains the verbatim text you want in the final comment with variables as needed If you wish to include XML tags in this style of comment you must use amp lt and amp gt to represent the and characters file project project file projectpathname summary 4fileDescription copyright 4 Date Developer Change date user Created lt file gt StyleCop compatible Xml based file header Note tha
63. ently it takes many minutes to retrieve and so for this reason Atomineer disables these commands in C C header files Doc All in This Scope This alternative command uses Atomineer s built in code parser rather than intellisense to understand the source code It reads the code line by line and attempts to work out the features of the text that represent valid code elements to document and it then documents them Because it does not rely on Intellisense it will generally work on uncompilable uncompiled code it will process code that lies in if blocks even if they are not currently enabled and it works equally well for all code languages and versions of Visual Studio and even on incomplete code snippets in short it gives much more consistent results than Doc All In File However there is a trade off Because it relies on interpreting the text in your source code it can occasionally become confused by unexpected syntax particularly things like macros and if blocks It operates by processing a scope so it cannot process for example several classes at a time if they happen to exist in one file and it does not have the capability of batch processing an entire project at once 48 So if you try one of the Doc All commands and the results are unsatisfactory please undo and try the alternative approach to see if that suits your needs better As a general rule of thumb Doc All In File Project Solution Chosen Files are best f
64. erted reformatted in the new style Any entries that are not considered legal by Atomineer will be marked as deleted with a prefix 3 Common Doxygen DocXml markup is automatically converted e g Nc ClassName see cref ClassName Ncode endcode gt lt code gt lt code gt 4 Where an old entry should be removed entirely add an entry like this within the Conversions section ingroup convertTo gt delete all ingroup entries 5 Where an old entry needs to be renamed add an entry like this author convertTo programmer gt convert all author entries to programmer 6 Aspecial pair of commands can be used to convert simple plain text lists into a set of tags e g To convert references c MyClass c BaseClass 74 into a set of separate entries you can use two forms references convertEachLineTo seealso cref stripPrefix will produce lt seealso cref MyClass lt seealso cref BaseClass references convertEachLineTo seealso stripPrefix c gt will produce lt seealso gt MyClass lt seealso gt lt seealso gt BaseClass lt seealso gt If an incorrect entry is converted such as a param or exception entry that describes a parameter or exception that is not present in the code the entry will be converted correctly but then added at the bottom of the new com
65. es are always provided internally by Atomineer user time daten day dayofmonth month monthofyear year pathname projectpathname projectfolder folder leafname extension project solution containingclass namespace assemblyname assemblyversion assemblyfileversion User s login name or the overridden name provided in the Atomineer Options The current time in the format specified in the Atomineer Options The current date in the format specified in the Atomineer Options The current day e g Tuesday The current day of the month as a number e g 2 The current month e g June The current month as a number e g 6 The current year e g 2009 Full pathname of the current file e g C MyProject Source MenuHandlers FileOpen cpp Pathname of the current file relative to the project folder or a full pathname if it s outside the project root e g Source MenuHandlers FileOpen cpp Project folder containing the current file e g Source MenuHandlers Leafname of the folder containing the current file e g MenuHandlers Leafname of the current file not including the file extension e g FileOpen File extension of the current file including the e g cpp Name of the Project containing the current file Name of the Solution containing the current file Name of the parent class struct interface or enum containing the curso
66. es will now be saved to the first folder in the above path i e C Code AtomineerSettings in this example In Source Control check in any preferences file s that Atomineer saves to this folder to allow your team members to use them Team member set up In the Atomineer options switch to the General Settings tab In the Preference Storage section enter the path s of your standardised folder locations with each folder path separated by a semicolon e g C Code AtomineerSettings D Code AtomineerSettings Get the preferences into this location using your source control system Assigning Custom Hot Keys for Atomineer Commands Atomineer will automatically set up hot keys for the primary commands but only if they are not already in use for any other commands However if you wish to change the default hot key assignments follow these steps In Visual Studio go to Tools gt Options Find the Environment Keyboard section In Show commands containing type Atomineer The Atomineer commands will be listed To add a hot key binding select a command click in the Press shortcut keys field and press the key combination you wish to use to execute the command When you are happy with the hotkey click Assign 11 Unattended Command line Installation Visual Studio 2005 2008 2010 2012 2013 Atmel Studio 5 x amp 6 x Visual Studio 2015 onwards You can install or uninstall the Atomineer add in from the comman
67. et an auto property P peer ee i public int Speed After 2nd execution a property with backing field private int mSpeed get return mSpeed set mSpeed value Example C CLI Properties public private Before int mInteger MyClass mComplexClass public property int Integer 1 int get return mInteger void set int value mInteger value b property const MyClass amp ComplexClass After const MyClass amp get return mComplexClass void set const MyClass amp value mComplexClass value j private int mInteger MyClass mComplexClass Example C Accessors public private int mInteger MyClass mComplexClass Before 92 public int GetInteger void const return mInteger ke void SetInteger int Integer mInteger Integer const MyClass amp GetComplexClass void const After return mComplexClass 3 void SetComplexClass const MyClass amp ComplexClass mComplexClass ComplexClass private int mInteger MyClass mComplexClass Copy As Text Default hot key Ctrl Shift C Copies selected text onto the clipboard in a simple clean format for use in other programs Usage Just as with a regular copy Select the text you wish to copy and execute the command If no text is selected the entire line containing the cursor will be copied Description When you copy text from Visual Stu
68. ext in a regular comment It has two lines summary Atomineer works hard to ensure that copying and pasting of regular text or code samples usually works better than with the default Visual Studio handling but if you are ever unhappy with the results you can simply undo to remove the Atomineer reformatting which will leave the text as Visual Studio normally pastes it Note If you use another Extension or Add in that monitors keypresses such as ViEmu it is possible that a keyboard handling clash could occur as both Extensions try to react to the same keypress To resolve this you will unfortunately need to disable the keyboard handling in one of the Extensions 38 Getting the Most out of Atomineer Introduction Atomineer does a lot of work behind the scenes to produce the best documentation it can from your code However it can only provide good documentation for code that it understands so understanding what Atomineer looks for can help you to get better results To start with understanding clearly what Atomineer does can help avoid disappointments and confusion e Atomineer does not document your code What Atomineer does is significantly accelerate the process of you documenting your code Its aim is to provide you a starting point that will minimise your typing effort Expect to tweak the wording and add information to complete the descriptions e Atomineer works hard to save you time when updating
69. h and can start tweaking some of the finer details Let s go back to the Doc General tab and look at the other options available there ions enerated Text Optio y this as this 0 Add Doc Comment 7 whis phvasing Desembe Jason Williams 1 Add author entries der Current culture ei eu d Add date Date Format Himi gt HTML mu ppercase for known annia T ifthe commentis updated again pee 7 the entry Cree 888 Remove highlighting with Invalid entries by ents process Inva When updating comm e Your User Name is optionally entered into Doc Comments in the remarks or author entry By default Atomineer will use your Windows Login name but you can type the name you wish to use into this field to override it e this phrasing controls the way that this object is described in descriptions e g If your class was called Vehicle these naming options would produce descriptions like summary Saves this object to a file summary summary Saves this instance to a file lt summary gt summary Saves this Vehicle to a file summary e The Date options allow you to set how dates are formatted in the remarks or date entries These use the standard Net format strings and cultures so d gives dates like 9 10 2011 and dd MMM yyyy produces 4 Feb 2012 e this phrasing allows you to control how Atomin
70. he difference between the handling of the WordExpansions and Prefixes sections is that for Prefixes only the first word of any symbol is processed all words are processed for abbreviation expansions 72 Automated Comment Conversion Atomineer can use its unique ability to parse multiple formats of comments to convert from legacy formats to a new style Any existing documentation in a valid XmlDoc Doxygen JavaDoc Qt JSDoc or JSDuck format or any other sufficiently similar format can be converted in this way In addition if your legacy comments are not in a form that Atomineer recognises directly it is also possible to apply custom pre processing of the comment text during the parsing process to convert your comments into a form that Atomineer can successfully parse In this way it is possible to automatically convert any machine readable legacy format to an Atomineer supported style and this process can even be applied to the comments throughout an entire project or solution As this conversion process is a relatively rarely used option it must be manually configured by opening the Atomineer Prefs xml file in your install folder usually Documents Visual Studio 20 Addins AtomineerUtils or Documents Atomineer and adding the following elements to the lt DocComment gt section Alt Separator value gt Alt LineHeader value gt lt Alt SeparatorB value You can set any text for the Sepa
71. his can be used to align assignments commas arithmetic logical bitwise comparison operators brackets strings numbers variables and keywords Alignment can be used to significantly improve code readability and clarity in repetitive blocks Usage There are two ways to use this command e Place the cursor next to a symbol that you wish to align to and execute the command Atomineer will search up and down from this starting point to auto discover the block of similar code lines to be aligned e Select a block of lines to be processed starting the selection from the symbol you wish to align to and execute the command Only lines that overlap the selection will be processed Description When executed this command will look at the closest text to the left or right of the current cursor position or the top point of the selection It then searches the block of lines to be processed for similar lines and inserts tabs spaces into these lines to align the matches into a column When used with a selected block lines that don t match the pattern e g blank lines will be skipped allowing tables with gaps in them to be processed in one pass For example the red line shows where the cursor can be placed when executing the command Text before aligning Result int age 5 int age 55 Align before int height 97 int height 97 assignments int age 5 int age 5 Align after int height 97 int height
72. ilsSetup exe Atomineer Pro Documentation vsix add in extension System requirements System requirements Acompatible Visual Studio A compatible Visual Studio version edition version edition Net 4 5 1 Windows XP Windows 7 or Windows 8 x 32 bit or 64 bit 1 2 Mb of disk space Net 2 0 Windows XP Windows 7 or Windows 8 x 82 bit or 64 bit 1 2 Mb of disk space e eoo If you have several installations of Visual Studio both versions of Atomineer can be installed side by side on your PC They will share preferences and customisations In this case it is recommended that you install the add in first Installing To install either version quit all running instances of Visual Studio and then run the relevant installer Installation will proceed as follows Visual Studio 2005 2008 2010 2012 2013 Visual Studio 2015 onwards Atmel Studio 5 x amp 6 x Run AtomineerUtilsSetup exe Run Atomineer Pro Documentation vsix Select an installation location Microsoft s VSIX installer will run This must be in a location that can be written to without administrator privileges e g in My Documents It is recommended that you do not change the default installation location Click Install to install the add in When the installer has finished Atomineer will be available in all compatible versions of Visual Studio and Atmel Studio Select the edition s of Visual Studio you wish t
73. ing which defeats the primary purpose of providing an instantaneous and lightweight viewer e The viewer is not currently interactive links will be displayed syntax coloured but they cannot be clicked to view documentation elsewhere in the system documentation pages are only shown for code elements as you move your cursor within the source code Document All in this Scope Default hot key sequence Ctrl Shift A Ctrl Shift S This command searches a file namespace class interface struct or enum scope using Atomineer s built in code parser and applies the Add Doc Comment command to each major code element within it Note that it does not recurse into nested child scopes so you may have to run it several times to document a whole file if it contains several classes Usage To document all code elements at global scope in a file place the cursor in the very first line of the file and execute the command To document all code elements within a specific scope place the cursor in the declaration that introduces the scope i e somewhere in the line with the namespace class etc text and execute the command Description When you execute the command the code within the next scope i e for C style languages from the following the cursor position will be scanned for child code elements to document The Add Doc Comment command will be executed on each adding or updating the comment in the usual way This processing can be
74. ing capitalisation Divide By Zero Exception Conversion to sentence form also expands any abbreviated words e g InfoMgr becomes Information Manager The first word of the text Divide The last word of the text Exception Everything except the first word ByZeroException Everything except the last word DivideByZero Lowercase the text Dividebyzeroexception Uppercase the text DIVIDEBYZEROEXCEPTION Uppercase the first letter of each word in a space separated sentence This Is A Sentence Sentence case the text uppercase the first character lowercase the rest This is a sentence Camel case a multi word symbol lowercase the first character of the first word uppercase the first character of the remaining words thisIsASentence Pascal case a multi word symbol uppercase the first character of each word in the symbol ThisIsASentence Attempts to pluralise a word This will give results like square squares box boxes party parties usually it works well but in some cases the heuristics will fail goose gooses DivideByZeroExceptions The leafname in text assuming that it is a filename or a fully qualified type name e g System Exception would return only Exception For generic template types such as List int this returns the main type without its type params i e List Converts the lt gt characters from a template generic type into so it can be safely embedded in XML documentation
75. ing documentation comments If a documentation comment already exists it will be parsed and updated for example if you add a new parameter to a method remove an exception thrown in your method or change a Property by adding a get set accessor the existing comment will be updated to reflect the new details effortlessly keeping the comment in sync with the code This feature can also serve to automatically convert most existing Documentation XML Doxygen comments into the Atomineer format see below for more details In addition the block will be optionally reformatted to keep it tidy Documentation entries will be formatted into a consistent ordering grouped together into related blocks with optional blank lines between them Within each block of entries e g param lists the text for the entries can all be indented to start at the same column to enhance readability If enabled the word wrap option will automatically reformat each comment entry to keep it tidy The indentation level of the first line of each entry will be used in all subsequent lines The word wrap will preserve blank lines any lines at a greater indent level than the first line of the entry and lines starting with certain text examples e g c f i e bullet lists starting with etc To deliberately force a new line you can end the previous line with two spaces Word wrap is suppressed for blocks of text that lie between pre code code
76. into the destination comment as a code example retaining the original prefixes on comment lines Note This only happens if you paste into a commented line pasting on a blank line adjacent to a commented line will not apply the reformatting If the paste reformatting produces an undesirable result in any case simply undo once to remove the Atomineer reformatting and leave the text as it would normally have been pasted 96 Notes To use the standard Visual Studio behaviour to exit the comment when pressing Enter press Enter twice in a row or type a Shift Enter add a newline at the current cursor position or Ctrl Enter add a newline before the current line If you enable disable any of these features you will need to execute Add Doc Comment once or restart Visual Studio before the change to key press handling will take effect Due to the way Visual Studio handles key presses this feature may interfere with or be affected by other installed add ins extensions that also process Enter key presses within comments If this occurs you can reconfigure Atomineer or the other add in to disable the clashing feature and restart Visual Studio Where possible Atomineer tries not to interfere with other add ins but the known issues are Visual Assist X has an option Advanced Corrections Auto extend multi line comments which provides much the same new line behaviour in comments as Atomineer Unfortunately these two features wil
77. ion and a full documentation comment which are appended to the source cpp file e All default parameters and modifiers like static are stripped from the implementation e Any block of C single line comments immediately above the function are concatenated into a single line and moved into the description field in the header e Askeleton function body is appended and in the case of simple types a simple default return value is provided e Adocumentation comment is automatically generated and the text cursor is left in the summary section When executed in a source cpp file This adds a declaration for the method in the header h file Where possible Atomineer will locate the correct namespace class to add the declaration into The new declaration is inserted at the bottom of the class For this command to work the cpp and h file must have a common filename and both be part of your Visual Studio Project 98 Header declaration Creates a new Thingummy containing the required number of Wotsits Thingummy CreateThingummy CreateInfo pInfo int NumWotsits 12 const Resulting source file implementation with doxygen style comment IB BI dd dd dd dd dd dd dd dd dd dd dd dd dd dd dd dd dd dd Hd Idi IL fn author date brief param param retval Thingummy MyClass CreateThingummy CreateInfo pInfo int NumWotsits Jason Williams 6 6 2005 Crea
78. ion relative search folder you configured above As you switch between different solutions Atomineer will dynamically pick up the relevant preferences Multi user Installation Atomineer only installs for the current user account on a given PC To install for multiple users you will need to re run the installer on each user account This is to allow each user to have their own independent Atomineer settings If you wish to share settings between these users we recommend keeping your settings in source control as described in the next section Sharing Preferences Customisations across Your Team Atomineer strives to be very configurable to allow everyone to get what they need out of it When installing Atomineer for a Team it is recommended practice to share the preferences and customisations via your Source Control system as follows D It s recommended that each team member uses a standardised location on their hard drive for their source code e g C Code Several similar locations can be used to accommodate different user setups if needed e g C Code or D Code 10 Master preferences set up In the Atomineer options switch to the General Settings tab In the Preference Storage section enter the path s of your standardised folder locations with each folder path separated by a semicolon e g C Code AtomineerSettings D Code AtomineerSettings Click Store Preferences on my Search Path and your preferenc
79. is tag within an entry simply adds to the output comment Instead use newlines within an entry to add newlines to the output comment but note that these may still be removed by the word wrap feature Any indentation in your template will also be used so you may have to remove unwanted indentation to achieve the desired result Note that multiple blank lines will be merged and any leading trailing blanks on the entire block will be stripped regardless of what is in the template Custom Elements The XML elements in your template are not limited to the standard ones that Atomineer knows You can add any element you like to add a custom entry For example you could add an author entry or a lt design document gt element Atomineer will then support these custom tags If you are generating external documentation with a tool such as SandCastle or Doxygen you will need to configure your documentation generator to handle these additional entries correctly design document Any element containing attributes other than the special ones listed below or text content will simply be copied into the documentation comment allowing you to add custom tags or override the output of the auto generated text provided by Atomineer with fixed text remarks TODO fill this in remarks 56 Note that most changes to rules and preferences will take immediate effect in Visual Studio but if you add new custom entries it will be
80. l result in the comment prefix being added twice on each line The recommended solution is to disable the Visual Assist X feature as it operates in isolation while Atomineer offers many typing aids that are enabled disabled together Vim add ins intercept Enter key presses and under some circumstances may clash with Atomineer Disable the Atomineer live aids if you encounter any problems using Vim key presses in comments 97 Deprecated Menu Commands The commands described below are included in the Atomineer Pro Documentation Add in for Visual Studio versions 2005 2013 and can still be used in those versions However these commands were not duplicated into the Visual Studio 2015 Extension Mainly because these commands are not particularly documentation focussed In addition some of these functions are now provided by Visual Studio or other extensions Implement Declare C method deprecated Default hot key sequence Ctrl Shift A Ctrl Shift l For C only This command allows you to e Create a skeleton implementation of a method from its header declaration e Adda header declaration for an existing implementation Usage Place the cursor into the first line of a function declaration implementation and invoke the command Description When executed in a header h file This converts the declaration for a method in the header and any contiguous block of single line comments preceding it into a skeleton implementat
81. lace a file header e Anywhere in the whitespace at the end of the file to generate a file footer e Anywhere in the first line of a code element namespace macro typedef struct enum class interface method function property or variable definition etc or in any blank lines or documentation comments immediately preceding the element e Anywhere within a normal non doc comment style comment block to simply reformat the text with word wrapping and execute the command This can be done from the Tools gt Atomineer menu the context menu or by pressing the assigned hotkey normally ctrl shift D Description When you execute the command the code around the cursor will be interpreted and an appropriate header comment will be inserted just above the current code element As much useful information as possible will be extracted from your code and any existing documentation comment and where possible default descriptions will be inserted to save you unnecessary typing 80 Documentation Viewer Default hot key sequence Ctrl Shift A Ctrl Shift V This Atomineer command opens a documentation viewer window This displays documentation comments in a human readable style similar to the sort of output you can generate with tools like Sandcastle Doxygen and JavaDoc IDocumentFactory cs x PixelPlot DocView IDocumentFactory vie hd Creates a new document del iy existing document Strech nterface needs to as bout
82. lation A task like creating and opening a connection to a server may require several lines of code Good documentation can supply an example that helps the reader to quickly achieve their most likely task Because of this a large number of classes and methods in MSDN are documented with a short example of usage for a typical case do you ever find yourself copying and pasting a snippet from MSDN documentation or some other source of pre written code snippets on the web e g CodeProject or StackOverflow to get you started on a task e When you don t have access to the source code it s irrelevant whether the source code was self documenting or not Usually in this case documentation needs to be provided in an external form PDF HTML CHM etc alongside the library binaries This documentation can be written in external tools but it is usually much easier to keep in sync if the basis of that documentation is extracted directly from source code comments 43 Unit tests and TDD are employed to help us to think about and design our code well Ina similar way writing down how we expect a method to be used forces us to explain it to someone else We need to think about it understand it and look at it from the point of view of the end user Documenting is a powerful way of improving the quality of the code and tests that we write Self documenting code is an important step in writing clean maintainable code but in all but the simplest ca
83. le mVariable or m Variable e C Get and Set methods will be created and inserted into the document above the preceding public protected private tag For known simple types int float etc the accessors will pass by value For unknown types it assumes complex types struct class and will pass by const reference The names used for the getter setter can be configured in the preferences e C CLI A property is defined and inserted into the document above the preceding public protected private tag e Ci This operates in two stages to give you control over the generated code 1 When applied to a member variable it is converted into an auto property 91 2 When applied to an auto property it is converted into an explicitly implemented property with a backing field The backing field will use the variable naming style configured in the preferences You can convert from a member variable to an explicit implementation by just executing the command twice in succession The preferences allow you to set a template for the backing field naming style For an auto property called MyProp the default a blank prefix is to generate a backing field myProp With a template specified other styles e g MyProp m_MyProp mMyProp Member MyProp can be generated Example C Property Before a member variable private int mSpeed After 1st execution ublic int Speed et s
84. mWordsInName numArgs zarglypex zarglypeBasex zargNamex sgetSet zeventSender event Tvpei attr The type of the method one of method property indexer delegate eventhandler alias for name The name of the method The name of the method including any generic type specifiers Extra info on the method normal static inline abstract virtual override The return type for this method const int The core return type for this method without modifiers int The number of words detected in name The number of arguments for this method Argument type where X is the 1 based index of the argument e g argType1 argType2 Core argument type without modifiers where X is the 1 based index of the argument e g argType1 argType2 Argument name where X is the 1 based index of the argument e g argName1 argName2 For methodType property or indexer the appropriate Gets Sets or Gets or sets text for this property indexer For methodType eventhandler only the sender of the event For methodType eventhandler only the type of the event When a method has one or more meta data Attributes assigned to it each one generates an attr variable e g attr conditional attr description The value of the variable is the list of parameters to the attribute e g the description text from a DescriptionAttribute This is usually used with the defined attr description syntax of the
85. mber variable declarations into Properties Accessors as appropriate for the current language The Property variant applies to C CLI while the Accessor applies to C standard Both commands can be used in C and they operate identically Default hot key sequence e C Creates simple inlined Get and Set methods to access a member variable making it much quicker and easier to make members private and properly encapsulate your class data e C CLI Creates a Property for your member variable implementing default get set methods e Cit Creates a Property for your member variable implementing default get set methods A two stage conversion is used It will convert a member variable into an auto property and convert an auto property into an explicitly implemented property with a backing field Usage In your C header or CH class place the cursor anywhere in the middle of a member variable or auto property declaration then execute the command Description Atomineer will convert a member variable declaration to a property accessor The style conventions used in the generated code can be configured in the preferences Other Features tab in the Create Property Accessor section The source member declaration need not match the configured naming style to be processed correctly it may have a lower case first character or an underscore as a prefix suffix e g variable 04 variable Variab
86. ment with prepended deleted entry just as would happen if you removed that param exception and updated an existing comment If unwanted just execute the Add Doc Comment command a second time to clean away these deleted entries Note that if the old comment format diverges too far from what Atomineer expects such as using Doxygen aliases or custom Documentation XML elements not mentioned in the Conversions rules the conversion may not work so well you may need to tidy up the comment manually or perhaps using a Macro Extension pre processing script see below before applying the Atomineer conversion For example the following Doxygen JavaDoc comment uses the alternate format described by the prefs XML above with JavaDoc style entries brief This is the brief description returns true if it feels like it param exampleParam An example parameter date 15 04 2010 author Jason 75 and it is converted to the following Documentation XML in this case using the default Atomineer format with the entries rearranged in the order dictated by the default template MM MM MB M MMIMMPMBMIMBMILHMMLIMPMPMHMPMAMIMMMMPIlMIIIIIIITPBMB MIL TTT LLL P T TTT TTT lt summary gt This is the brief description lt summary gt lt author gt Jason lt author gt lt date gt 15 04 2010 date remarks Jason Williams 16 04 2010 remarks lt par
87. ments in the current file which can be useful when rewriting legacy documentation to be sure that none of the old documentation is accidentally re used In some cases generally blocks of code where many lines follow a similar pattern such as a list of assignments a table of values repeated calls to the same method with different parameters or a multi line if condition code readability can be greatly improved by lining up the interesting components of each line such as parameters into columns This command uses the context near the cursor to intelligently decide what you would like to line up into a column and how so it can be used for a wide variety of alignment situations Instantly convert a member variable declaration into an auto property or accessor or convert an auto property into a property with a backing field Copies source code to the clipboard without any font formatting information or unnecessary indentation ideal for copying code snippets into documentation in other programs such as Microsoft Word Deprecated Atomineer Commands Atomineer provides the following commands for Visual Studio versions 2005 2013 These commands are no longer available in Visual Studio 2015 as their functionality is now available elsewhere and or is only rarely used Implement Declare C Method Open C source header Given a header file declaration create a skeleton implementation Or given a source file implementation
88. mment blocks with a special format used to distinguish them from normal comments Typical styles for this are fers A multiline comment C C Java S Vee A multiline comment C C Java 7 a block of one or more single line comments using rather than C C Java 15 a block of one or more single line comments using rather than Visual Basic Adding the descriptions above to our block format we get a basic documentation comment for our method Here s how it would look in the basic XML Documentation format summary Finds a user account in the database summary param name userName gt The login name of the user to find Must not be null param exception cref InvalidArgumentException Thrown if username is null empty contains spaces or is otherwise invalid exception returns 1 if the username is not found or the database ID in the UserTable of the user s record returns And the same thing in a basic Doxygen JavaDoc format brief Finds a user account in the database param userName The login name of the user to find Must not be null exception InvalidArgumentException Thrown if username is null empty contains spaces or is otherwise invalid returns 1 if the username is not found or the database ID in the UserTable of the user s record
89. mp Live Typing Aids CO Convert lt gt 8 int doc comments mmentif you type fil or Maintain indentati extend comments comments and single ine co ab to navigate ein on bullets as you typ mments returnjentet will between documentation entnes 7 Create Atomineer doc co matting of text thatis pasted into Jl 7 Improve for 7 Use Tab Shit T The aids include e If you type in CH or in Visual Basic on a blank line Visual Studio will add a skeleton Doc Comment for you Atomineer can optionally extend this behaviour in two ways 1 Typing will add a doc comment in all supported languages C C C CLI Java UnrealScript 2 Instead of an empty skeleton comment a complete Atomineer comment will be generated e If you type a newline enter return Atomineer will assume you wish to continue typing the comment on the next line It adds the comment prefix and indents the cursor to match the previous line so you can just type description text without worrying about manually formatting the comment block In addition if your line looks like it is part of a bullet point list or numbered list 1 2 3 ora b c Atomineer will automatically add the next entry for you For example typing without the aids you might get brief An enum indicating whether the vehicle is A bus A train An aeroplane A truck But with the live typing aids you ll get this result Qb
90. mproving the readability of the source code 16 1111111111111 1 11 1 1 11 11 111111111111 111 111111111 11111111111 lt summary gt Finds a user account in the database lt summary gt param name userName gt The login name of the user to find Must not be null lt param gt Hid exception cref InvalidArgumentException JH Thrown if username is null empty contains spaces or is JHE otherwise invalid lt exception gt lt returns gt JE 1 if the username is not found or the database ID in the UserTable of the user s record returns 1111111 1111111 11 1 1 11 1 1111111111111 11 111111111 11111111111 Or AE brief Finds a user account in the database param userName The login name of the user to find Must not be null exception InvalidArgumentException is thrown if username is null empty JHE contains spaces or is otherwise invalid returns 1 if the username is not found or iti the database ID in the UserTable of the user s record AE These are just examples of what is possible There are many alternative ways the comment can be arranged to provide a compromise between readability and compactness Generating new documentation Atomineer uses thousands of special rules to generate meaningful documentation based on the types of code elements e g constructors destructors ope
91. n on to the next line so the tag is on its own summary Finds the user account The second Combo Box This controls how each line in the entry is indented if the entry flows on to more than one line At the start of each new line in the entry it can e Left align the text so that all lines start at the left edge of the block Two examples are given here showing the difference between adding a newline after the tag and adding a space after the tag this illustrates why this option is for after each newline Wisumnary Finds the user account in the user database summary summary Finds the user account in the user database summary 28 e The Indent the text one space tabstop options insert a space or tab to indent the entry text sulffary Finds the user account in the user database summary ge d tt Finds the user account in he user database lt summary gt e Align the text with the start of the previous line inserts enough spaces or tabs to indent the entry text so that it forms a column of text sulllary gt Finds the user account in the user database lt summary gt lt summary E the user account in the user database lt summary gt The third combo box This combo box is only relevant for XML Documentation as it affects the placement of the end tag which is not used in the other documentation
92. nabled by default but can be disabled if you wish see the typing aids box on the first tab of the Atomineer Options For NET projects Visual Studio has a handy feature If you type the start of a documentation comment block in C or in Visual Basic above a code element then it automatically creates a skeleton comment block Atomineer extends this behaviour in the following ways 1 The Atomineer feature works in all supported languages not just the NET languages 2 The comment block is generated using the Atomineer documentation engine so the comment uses your configured comment style and of course all the auto generated documentation is filled in for you It works equally well for Doxygen Qt JavaDoc and XML documentation 3 The comment block will be indented to the same level as the code element it documents rather than being dumped at the place where you typed the or and the other Atomineer formatting helpers such as controlling the number of blank lines between code elements will all apply as normal In addition Atomineer offers enhanced editing within or in Visual Basic Documentation Comment blocks and any regular comment blocks made up of single line comments in Cit C C Java JavaScript TypeScript PHP and UnrealScript or in Visual Basic These features help you edit the comment body text without having to continually insert and delete comment or prefixes by hand to keep the commen
93. ndicate that it is currently being overridden Any changes you make to the preferences will now only affect your doc comments in that one coding language You can clear the overridden preferences at any time form the same submenu This will remove the language specific preferences and return to using the global settings for this language Choose Edit Global Settings to return to editing the main preferences 24 Automatic Tidying features Whitespace Control Now that you have the block outline you require move down the Doc Style tab to the last Style setting 1 UU fter iff region use egen Dey pp m Except after use Ec S 45 ov c comments and below th 2 above do Enforce blank lines L The Enforce blank lines checkbox enables or disables a white space control feature With this enabled when Atomineer generates or updates a documentation comment it will also add or remove blank lines above and below the comment to help keep the code tidy and consistent You may enter 0 to remove all blank lines between code and comments like this m int SomeValue get set summary Opens the database summary a void OpenDatabase Or you could require 2 blank lines above and 0 below int SomeValue get set summary Opens the database summary Ss void OpenDatabase Or 3 blank lines above and 1 below int SomeValue get set lt summar
94. necessary to restart Visual Studio before the templates are picked up by Atomineer Variables Variables see below can be included in your template using the varName syntax For example to create a fixed text entry for remarks that contains the author s name and the date you can add an XML element like this lt remarks gt user date lt remarks gt In addition to internal Atomineer variables the varName syntax can be used to expand OS environment variables Note that an Atomineer variable will take precedence over any environment variable of the same name Special attributes for code element templates The following attributes can be added to the main template xml element to control how this type of code element is documented access AccessLevels If specified this attribute overrides the global Restrict documentation by access level preference allowing finer grained control over what is or is not documented based on its access levels For example to only allow methods to be documented if they are public or internal modify the method element like this method access public internal method You can also use access all to override the default to use an unrestricted access level or accessz none to totally disable documentation of that type of code element If an access level is applied to a property then it will affect the accessors independently i e for public get private set with
95. nes or paragraphs e Some documentation entries are standalone e g summary returns only occur once in any documentation comment while others may occur several times forming a group of similar entries e g if a method has 3 parameters there will be a group of 3 param entries e Inthe following a Tab means moving to the next tab column in the document If your Visual Studio is configured to do this with spaces Atomineer will insert spaces to achieve this if it s configured for tab characters Atomineer will use tabs Atomineer offers a simple but powerful set of options to control how the entries are laid out Although each of these options is simple they interact with each other so understanding exactly what each option does to the text is very helpful when trying to achieve a particular format This is why the options are worded in a very particular manner 27 Documentation Entry Formatting The first combo box Atomineer starts to build an entry by outputting the tag e g lt summary gt In between this tag and the entry text you may insert e Nothing This means the entry text follows directly after the tag lt summary gt Finds the user account e A space character causes a single space to be inserted lt summary gt Finds the user account e Atab character causes a single tab to be inserted lt summary gt Finds the user account e A newline causes the text to be moved dow
96. nnect if your PC is behind a Proxy Server About Atomineer Pro Documentation Shows a dialog providing information on Atomineer the installed version and the number of times you have used it Internal SuppressUI and AllowUI commands These commands are not available on the menus They are used to suppress user interface prompting to allow automated execution from a Visual Studio macro or extension Usage The SuppressUI and AllowUI commands are only available to macros and extensions and hotkeys They suppress or allow reporting of any problems via information dialogs Suppression of this Ul allows macros extensions to automate execution of Atomineer commands without being stalled by dialogs popping up Just include the following commands at the start and end of your macro extension command DTE ExecuteCommand Atomineer Utils Commands SuppressUI your macro extension code here DTE ExecuteCommand Atomineer Utils Commands AllowUI Note that this option suppresses all UI prompts from Atomineer but Visual Studio itself may throw up Ul in some cases for example if it encounters a read only file a solution to this is to check out make all files writable before running your automated task 94 95 Live Comment Editing Enhancements Atomineer can optionally track changes within comments and documentation comments as you edit them and offers the following enhancements to the standard Visual Studio behaviour These are e
97. nts list and if a match is found it is replaced as specified In this case the sentence will be converted to open TCP IP connection Although this is primarily used for upper casing acronyms it can be used to make any substitution desired e g atomineer could become At mineer e Prefix removals This works just like the Abbreviation expansions but is only ever applied to the first word of a name and hence can be used to eliminate any coding prefixes your team employs e Conversions This special section describes how to convert entries between Documentation XML Doxygen and JavaDoc formats allowing you to convert legacy comments into a new format Note that the conversions section won t handle everything but if you let us know your requirements we may be able to incorporate additional features that will support your conversion needs lt UserVariables gt Section When generating documentation Atomineer uses variables to pass information into your rules to allow information to be stored during rule execution and to control the output that Atomineer generates The User Variables section allows you to override the built in variables and add your own custom variables These can be output in description text or used in subsequent variable definitions using the varName syntax see below The default variables also allow you to control certain features or text replacements in the rules and templates These variables are as
98. o install into and click Install to install the Extension When the install has completed Atomineer will be available in all selected editions of Visual Studio To upgrade an existing version from a free trial or to a newer version of Atomineer just run the installer and Atomineer will be upgraded in place There is usually no need to uninstall any version of Atomineer prior to installing another version Quick Setup Wizard For first time installs the Quick Setup Wizard will be shown for the add in this is shown immediately when installation is complete For the extension it will be shown the first time you run Visual Studio after installing The wizard allows you to choose your preferred documentation style from a set of common defaults On each page of the Wizard just select the style that most closely matches your requirements and click Next Note You can change all of these settings later or re run the Wizard from the Atomineer Options If you skip this step by clicking Cancel Atomineer will just use defaults Preferences and Customisations Location Once installed the software will use the following folder s to store preferences and customisations Visual Studio 2005 2008 2010 2012 2013 Atmel Studio 5 x amp 6 x Visual Studio 2015 onwards Atomineer is installed to the user supplied location and uses this to store preferences customisation files The default location is
99. o read through the code in a method to understand what its primary function is then that method is poorly named If parameters have ambiguous names programmers will find the code slightly harder to understand By helping Atomineer to produce better documentation you will also be writing code that is easier to read and understand better self documenting code By using Atomineer many users find that their coding style is gently massaged in the direction of these best practices if Atomineer documents something well it usually means it s cleanly written if not it can be a sign that Atomineer has been confused by some aspect of the code such as a syntax error or unclear naming Finally if something isn t working as you d like it ask us support atomineerutils com for help Many situations can be improved with only small tweaks to the XML rules that drive Atomineer We are more than happy to help you fine tune your results and to hear of ways we can improve Atomineer and will usually give you a definitive answer in less than 24 hours 42 Self Documenting Code and Doc Comments Atomineer can only provide information that it can extract from your source code That means that it can t usually say much more about your code than your code already tells you So why document the code at all This logic misses a number of key points e Self documenting code is seldom self documenting It s descriptively written easier to un
100. only tabs Notes e The automatic block detection works best on blocks of code separated by blank lines If you don t separate blocks in this way you may find you need to explicitly select the block to be processed to help Atomineer align the text as required e Although it is targeted at code this command works on any text including text within documentation comments XML or CSV files etc e The algorithm used by Atomineer is a generalised one The advantage of this is that it is not limited e g to only aligning assignments but the compromise of the design is that on occasion you may find an example where Atomineer aligns something you didn t want it to In these cases you may need to be more explicit select only the lines you wish to affect or apply the alignment by hand You can always undo if the alignment doesn t achieve what you want e Visual Studio provides automatic formatting as you type this can remove the extra whitespace provided by the Align Columns command To avoid this happening go to Tools gt Options gt Text Editor gt language gt Formatting and adjust the Spacing options provided You can test the results by using the Edit gt Advanced gt Format Selection menu option to reformat a chunk of code to see how Visual Studio treats the aligned code 90 Create C or C CLI Property Create C Access Methods Ctrl Shift A Ctrl Shift A Ctrl Shift A Ctrl Shift P These commands both convert me
101. or net languages C VB while Doc All in Scope is frequently more effective for C C and Java 49 Documentation Rules and Templates Atomineer uses special XML templates that define the documentation entries that make up a comment and the order in which they appear Each code element type classes methods etc has its own template so you can precisely control your documentation comments When there s no existing documentation entry for a code element and Atomineer can t find any appropriate user supplied documentation in the same class or base classes that it can make use of it falls back to a simple but surprisingly powerful rule based auto generation system This system is entirely data driven from rules defined in a simple XML format which are easily changed or augmented to suit your own coding style If you do modify your rules or have any suggestions for improving the default rules please consider emailing us your feedback so we can develop and improve the rules to cover different coding styles and situations better Custom Rules Files To add custom rules open the Atomineer options and switch to the Advanced Customisation tab For each section of the rules there is a button Click the appropriate button and that section of the rules will be exported to a separate custom XML file and then opened in your editor Note that the default rules are copied as an example to help you get started but you should comment them ou
102. or generic template type parameters The following special variables can be used in these sections isout y or n indicating if the type parameter is covariant out isIn y or n indicating if the type parameter is contravariant in lt Enums gt Rules used to generate the description for enumerated types The following special variables can be used in this section specialType The type of the enum enum bitfield lt Typedefs gt lt Variables gt lt Parameters gt Rules used to generate the description for parameters variables and C C typedefs Note The Execute Command is used to include duplicate the Variables rules into both the Typedefs and Parameters sections The following special variables can be used in these sections Ze The type of the variable const int typeBase The type of the variable not including any modifiers int index The 1 based index of the variable within the method s variable list Siong The first word of the variable often used for prefixes e g m_ lpsz etc 69 coreName isPointer isReference The name with the first word removed to allow processing of prefixed names y or n indicating if the variable type includes a or y or n indicating if the parameter type includes an amp or ref In addition the following variables are available only for the Variables section isEvent y or n indicating if the variable is an
103. our code Atomineer only parses the code near the location you wish to document so it has no way of understanding what these special code symbols represent When parsing class and method declarations Atomineer can apply optional regular expression replacements to the text before it is parsed This does not change the code in the document being processed but just the view Atomineer has of it This allows users to convert in house types typedefs and macros into a form that Atomineer can handle better 76 To add regex replacements edit the Pre processing Rules in the Atomineer preferences go to the Doc Advanced tab and click the Pre processing button and add one or more entries like the examples that are provided for Methods MethodDecl Replace pattern OurTrueFalseType replacement bool continue true Replace pattern OUR_TYPE bool replacement bool continue true gt MethodDecl or for Classes Structs Interfaces ClassDecl Replace pattern OurTrueFalseType replacement bool continue true gt Replace pattern OUR_TYPE bool replacement bool continue true gt ClassDecl The pattern is a standard regular expression to be matched in the source code when it is found each match will be replaced by the plain text replacement value The continue attribute can be set to true or false to control whether or not any following Replace rules are exec
104. ow The global variables listed above and any User variables you have set can be used within these rules In addition the following variables are always set for each code element being documented inanes The name of the item being documented e g m SomeVariable some variable sName The name of the item being documented converted to a sentence form words separated by spaces Anything that looks like a common prefix e g m_ will be removed e g some variable sNameRaw As sName but without any prefix removal e g m some variable In addition to the rules described above each of these sections can add an optional prefix or suffix to the generated description text These are set as attributes on the section e g 68 lt Exceptions prefix Thrown when suffix gt lt Exceptions gt The special cases for the various code elements that can be documented are handled in a number of sub sections of the AutoDoc section and are described in detail below lt File gt lt Namespace gt lt Interfaces gt lt Exceptions gt Rules used to generate the description used in respectively e Tor File header comments fileDescription e for Namespace comments e for Interfaces e for any Exceptions thrown in a method e for any Generic Type Parameters in a class or method For these sections no additional variables are available lt TypeParameters gt Rules used to generate the description f
105. p www atomineerutils com preprocessingmacro txt To install this code as a macro VS 2005 2008 2010 do the following e In Visual Studio go to Tools gt Macros gt Macros Explorer A view pane will appear in the Visual Studio window that shows your Macros by default this may be empty or show RecordingProject in the tree view e Right click on the Macros root entry and choose New Macro Project A dialog will appear e Type ameaningful name for the Macro Project we suggest Atomineer and will assume this name below and click Add Your new project should now appear in the macro list and fold open to show Module1 e Right click Module1 in Atomineer and choose Rename Rename it to Custom you may use any name but we will use this name in the example below e Right click Custom in Atomineer and choose Edit A new Visual Studio Macros window will appear e Select all in the macro code window containing the input focus and paste in the macro code from here e Finally choose File gt Close and Return In Visual Studio versions from 2012 onwards it will be necessary to write your code into a Command within an Extension and install the extension within your copy of Visual Studio If you wish to do this please contact us and we will be happy to supply a pre built Extension with example code you will then only need to tweak the conversion code to handle your own comment format The example code above will convert
106. p and use of blank lines both within the comment and between the comment and any surrounding code In addition to generating documentation comments on code elements If Add Doc Comment is executed in the top line of a file Atomineer will replace any existing file header with a new one in your configured style If Add Doc Comment is executed within a documentation comment or a regular comment Atomineer will apply word wrapping to the comment to tidy it up This is so that creating and updating all code documentation can be done with a single convenient hot key that applies an appropriate action based on the context 18 Note that word wrapping does not happen live as you type you must execute the Add Doc Comment command to re wrap the comment when you want it to be done This is because word wrapping can be destructive of important formatting such as in code snippets By only wrapping when you execute the command any unwanted side effects can simply be undone Finally if Add Doc Comment is executed in any other text based file format Atomineer will add a file header footer or catch all comment to the file These are somewhat simpler than the documentation comments that are generated for the file formats listed above but can still save considerable time and effort when documenting other source files SQL XML HTML python ruby etc Note that these comments will not be updated by Atomineer only created Updating exist
107. p to indicate the legal entries in your new comment format and how they should be ordered within the new comment block Any entries that have the same tag in both old and new formats e g param param will be 62 automatically converted reformatted in the new style Any entries that are not considered legal by Atomineer will be marked as deleted with a prefix 3 Common Doxygen DocXml mark up is automatically converted e g c ClassName see cref ClassName gt code endcode code code 4 Where an old entry should be removed entirely add an entry like this within this Conversions section ingroup convertTo gt delete all ingroup entries 5 Where an old entry needs to be renamed add an entry like this author convertTo programmer convert all author entries to programmer 6 Aspecial pair of commands can be used to convert simple plain text lists into a set of tags e g To convert references c MyClass c BaseClass into a set of separate entries you can use two forms This form references convertEachLineTo seealso cref stripPrefix will produce seealso cref MyClass gt seealso cref BaseClass gt While references convertEachLineTo seealso stripPrefix Nc will produce seealso MyClass seealso seealso BaseClass seealso 63 AutoDoc Section Commands Atomineer s au
108. r or the file leafname if intellisense information is unavailable Note that you can use containingClass Leaf if you don t want the fully qualified name The namespace portion of containingClass Assembly name for the Project containing the current file Assembly version Assembly file version 54 zassemblytitle Assembly title sassemblydescs Assembly description massemblycompany Assembly company name zassemblycopyright Assembly copyright zassemblytrademark Assembly trademark Notes e f you create a variable with the same name as a global the global will be replaced by your definition e The type specific variables e g retType cannot be overridden Templates Section There are two templates sections DocXmlTemplates used for generating Documentation XML comments and lt DoxygenTemplates gt used for Doxygen and JavaDoc comments These two sections are identical in operation but there are slight differences to the actual format used to better support these different systems In both cases the types that can be independently templated are e file e namespace e enum bitfield e struct class interface e method property indexer delegate constructor destructor c finaliser cH operator eventhandler eventsender If no template is supplied for a type a default Atomineer layout will be used For example here is a template for a Method and the comment that it generates lt method gt
109. rator top line of the comment block SeparatorB bottom line of the comment block and LineHeader prefix for all lines within the block If the separators and or line prefix are not used you must set value None If you wish to convert from JavaDoc JSDoc JSDuck Qt or Doxygen format then you must also make sure that the Doxygen command prefix is correctly configured Look for the lt Doxygen gt section in the Prefs xml file which contains a CommandPrefix entry Set this as appropriate i e one of these values CommandPrefix value CommandPrefix value When you execute Add Doc Comment on a comment in this alternate format it will be converted into your configured primary format The standard tags summary brief returns return seealso sa etc will be converted automatically as required including embedded mark up like c see Any custom tags used in your old format will simply be treated as embedded text appended to the previous entry unless they match a custom entry tag that you have added to your comment Templates if a matching template entry tag is found the old comment data will be converted to the new documentation style and inserted into the final block as dictated by that template Note that you can also use the aliases attribute in your Template to allow conversion of the entry name for example you may wish to change your comments from using throws to exception 73 C
110. rators event handlers indexers etc commonly used names from NET MVC MVVM MFC Qt stdlib etc e g ToString GetHashCode common naming styles e g GetXxx SetXxx XxxForm XxxException common abbreviations ptr gt pointer wnd window and the context in which an element is used e g sender in an event handler or the number of parameters to an Equals method etc Perfect documentation can t always be achieved but Atomineer attempts to provide the best documentation it can so that even though you will often need to finish the comments yourself the typing involved is minimised For example Atomineer optionally provides e The declaration of the code element being documented e Abrief summary of the code element containing an auto generated description e The name of the author and current date 17 All parameters generic type parameters and any return value are entered into the comment as required with meaningful auto generated descriptions where possible Atomineer will attempt to keep related blocks of entries tidy by grouping them together and formatting them with indentation and word wrapping and it can automatically insert blank lines between groups to make comments more readbale The cursor is positioned in the lt summary gt section of the comment ready for you to describe your code Atomineer uses some very powerful systems for generating the documentation automatically A user editable rules s
111. rief An enum indicating whether the vehicle is A bus A train An aeroplane A truck Press return twice in a row to exit this special comment editing mode e All the documentation comment formats will allow you to embed HTML formatting commands like lt b gt bold lt b gt and XML Documentation requires the comment body to be valid XML For these reasons you can t use the characters amp lt gt within your comments as they will cause errors in external documentation tools When updating your comment Atomineer can detect and correct these standalone characters converting them into the 37 HTML XML entity codes amp amp amp 1t and amp gt so that they remain compatible with XML HTML formatting e f you paste into a comment or documentation comment Atomineer can automatically reformat the pasted text to integrate it more cleanly into the comment If you copy a chunk of an existing comment and paste it into another comment the comment headers will be replaced so copying this Some text in a regular comment It has two lines and pasting into this at the arrowed location lt summary gt My Doc M d summary results in summary My Doc Comment Some text in a regular comment It has two lines summary instead of this summary My Doc Comment Some t
112. s Vehicle EngineParameters engineParams lt The engine parameters block Configure Doc Comment Layout Formatting Now we can move on to the actual Doc Comment Entries within your comment block Switch to the Doc Formatting tab and look at the first set of options Settings erFeatures Genera ick Setup Formatting Doc General Doc Advanced Oth as Quick Setup Doc fo 5 a elcome Doc Style e Dito Entry Form mment x Add Doc Co Within each doc comment entry a newline Between the tag and the entry text insert aigu v text line After every newline in the et a newline v Keep short enties as a single lin xt and the end lt tag gt insert ment block Between the entry te e doc Com from the left of th haracters f xa 10 c 7 Word wrap te The options within this tab can be set up quickly by clicking the Quick Setup button to re run the initial setup wizard However you can gain much finer control of the formatting if you edit the options on this tab directly First some background to explain these options e Each documentation entry is made up of a start tag command which may look like lt summary gt summary summary Or Summary depending on the comment format in use This is followed by the description entry text for the entry For XML only the entry is completed by a corresponding end tag lt summary gt e A documentation entry may occupy a single line or may be continued over several li
113. s files with cs file extension Database only process files with a Database prefix o Partial classes Atomineer can be instructed to only document a partial class if the class name matches the filename e g partial class MyClass will be processed in MyClass cs but not in MyClass Statics cs ensuring that the class itself is only documented in a single location Note that the contents of the class will still be documented in these files o Read only files can be skipped This can be used with some source control systems to only document files that are checked out for editing e Atomineer normally documents all code elements in a file However sometimes you might like to only update existing comments to refresh them or convert them to a new style At other times you might like to leave existing documentation alone and only add new comments for code elements that were previously undocumented This can help you to avoid touching files unnecessarily and of course significantly speed up processing if only a few elements need to be documented e Finally you can control whether or not file headers should be added to the processed files and the generation of author date entries can be temporarily suppressed during processing Progress will be shown in the Visual Studio status line and you may hold down the Escape key at any time to abort processing After processing details of what was documented are reported to the Visual Studio
114. se Code Analysis and external doc tools continue to run smoothly You don t have to place the cursor perfectly to update a comment with Atomineer anywhere in the whitespace or comment above a code element or anywhere on the first line of the code declaration is close enough In net languages you can also execute Atomineer anywhere within a method s body to document it 39 After adding or updating a comment Atomineer tries to leave your cursor in a useful location When commenting prefixed variables IpszName mSize Atomineer automatically removes the prefixes to make the descriptions cleaner Atomineer separates the words in method names by detecting camelCaseNaming PascalCaseNaming and underscore_separated_naming styles It tries to use this to generate a proper sentence form words with spaces for the name where possible expanding abbreviations ptr gt pointer db gt database etc applying correct capitalisation for acronyms HTML XML etc phrase correction Numltems gt Number of items and word reordering FileSize gt size of the file to generate a more readable natural English description from the name e Atomineer is highly configurable If it is not producing what you require it is often possible to fix it If your company has a nonstandard coding convention Atomineer can probably be adjusted to accommodate it If it is doing something you find annoying or you think it is interfering with another addin
115. sense CodeElement database for all code elements in the current File Project Solution It will then proceed to document each in turn Progress will be shown in the Visual Studio status line and you may hold down the Escape key at any time to abort processing After processing details of what was documented are reported to the Visual Studio Output window in the Atomineer Pro Documentation section This command can be used in the following ways e Convert legacy comments into the configured Atomineer format e Quickly update all existing documentation after changing the Atomineer block format or preferences e Automate an initial documentation pass on a large codebase After executing this command it is highly recommended that you read through and update the resulting documentation to be sure that it is complete correct and accurate Important Notes e This command is affected by the restrict documentation by access level preference By default all code elements will be documented but this option can be used to restrict the generated documentation so that it only applies to code elements with the correct access level e The command relies on Visual Studio Intellisense information to determine what to process so in some cases it may not be able to process the code primarily this depends on the version of Visual Studio in use whether the solution has been successfully built and how well Visual Studio supports the code language
116. ses it is just the first step For example here is some hard to understand code int j Opt string c string n If we make it self documenting with descriptive names it becomes clearer int j ReadUserOption string categoryName string optionName in fact it seems fairly self explanatory until you see the same code with documentation Does it work like this W i W i W i W i W i W i W i W i W i W i W i W i W i int j lt summary gt Reads a named user option value from the UserOpts xml file lt summary gt param name categoryName gt The name of the category group containing the option For global preferences pass in null or string Empty param param name optionName gt The name of the option within the parent category This may not be null Empty param exception cref ArgumentException gt Thrown if optionName is null empty exception exception cref InvalidOperationException gt Thrown if the options file is missing or could not be read or the value was not found exception exception cref FormatException gt Passed if the option value couldn t be parsed as an int exception returns The option value lt returns gt ReadUserOption string categoryName string optionName 44 Or perhaps it doesn t throw exceptions but passes back a spe
117. shes actions like Open from states like IsOpen Prefer to use Boolean names with the positive meaning i e IsFound rather than NotFound Abbreviations are useful in code for removing unnecessary verbosity as long as they are consistently applied Atomineer will recognise many common abbreviations e g ptr gt pointer and acronyms e g tcpip gt TCP IP to generate clean natural English descriptions so your documentation can be readable while your code is compact Hint If your team uses bespoke conventions it s easy to add custom rules and abbreviations to Atomineer to help it produce good results from your codebase Be specific Avoid overloading names with many meanings E g Where a parameter has a different meaning when used in different methods use a distinctive name e g replace the vague term id with specific descriptive terms like userld serverld fileld Atomineer will copy documentation from same named parameters in your class so using each name for one purpose really maximises the benefits of this feature Use OO practices e g use the single responsibility principle and store code one class per file These practices help because simpler operations are more easily described by brief names OO code files also tend to be smaller reducing the scope of names which improves their consistency and speeding up Atomineer processing and with OO naming generally becomes more consistent as
118. ssaececeescesseseaaeeeseesseesnensaeeeeeesseeees 19 Deleted entries Ee 20 Additional TDS n tete RR WIN 20 Configuring Atomineer etn etes e o IR ie 21 Set thie Comment Forrmat 2er ett ee re e et e am e et er e tee ee nn 21 Choose the comment block style Separators sesenta 21 Choose the comment block style Line Prefixes eessseseeseeeeeeeee rennen ennemi nnn 23 Advanced topic Choosing different styles for each coding Language 24 Automatic Tidying features Whitespace Control 25 Special Cases for Simple Comment Styles cccssccccecessessnseceeececsssesesaesececsseeseeaeeeesessseseeaeeeeeens 26 Configure Doc Comment Layout Formatting ccccccscccsssceessececsecesseecsseeeesaecesseeceseeecsaeeeeaaeceeseeens 27 Documentation Entry Formatting eene nnne iie nnn nnn inihi nin aiii i iei iint 28 Word Wrapping fA seb ttn ettet eet nete ete sd 30 Special case for short entries esses eese nnne nnne nennn nasse nennen sanas sensn setis a sans sn nnn 31 Special Cases for Groups of Entries c cccccccccssssssssecececessessneeeeeeecessesssaeseeecsssesesaeaeeeesessseseseaeeeeeens 31 MINUM E 33 Using Intellisense ee e e eee PER E REO ea PEEL NN E TRE le 34 XML Documentation Options sssseseee n emen nnn nnnm nnnm nnn nnns nsns EE ETE sensns 35 Doxygen JavaDoc Qt Documentation Options ccccccscecesscecsseceesecess
119. ssing which usually completes successfully in due course Open files will be processed and left open and a new undo step will be generated for the changes made Non open files will be opened processed saved and closed no undo will be available in these files If you wish to review all the changes it is suggested that you check all work in to source control before executing this command so that the results can be easily diffed at leisure Document All in Chosen Files This command applies any of the other Doc All In commands first allowing you to set a number of additional options controlling exactly which file s should be processed which code elements to process and how the processing should be customised Usage Place the cursor anywhere in a source code file within the project you wish to document and execute the Document All in Chosen Files command Description When you execute the command Atomineer will show an options dialog with 4 sections In the first section choose the main set of files to process the current file all open files all files in the current Project all files in the current Solution If more than one file is selected the second section allows you to apply filtering to further restrict which files are processed o A regex filter can be applied Any file whose leaf name matches the regex will be processed any which does not match will be skipped For example cs will only 85 proces
120. t block tidy These typing aids include 1 When you press Return Enter to insert a new line in a comment Atomineer will automatically extend the comment onto the new line duplicating the comment header and indentation from the previous line so that you can continue typing within the comment without having to manage the comment and text indentation If you wish to exit this comment editing mode press Return twice in a row the first press will extend the comment and the second will remove the comment header to leave you on a blank line 2 If the current line of your comment seems to start with what looks like a bullet point or a numbered list entry e g 1 2 3 or 1 2 3 or a b c etc Atomineer will automatically extend the list by entering the next bullet number on the new line 3 Whentyping in comment block if you press Delete to delete the newline at the end of a line Visual Studio will append the following line If the following line continues the comment block Atomineer will strip the indentation and single line comment prefix to concatenate the comment body text in a cleaner way 4 When pasting text into a comment block Atomineer will automatically reformat it as appropriate to integrate it into the destination comment Plain text will be converted into comment text Comment text is converted if necessary between normal and doc comment formats code examples that include a mixture of text and comments are embedded
121. t maximises the quality of documentation Atomineer will generate minimising the time and effort required to complete the documentation 47 Using Doc All in File versus Doc All in Scope These two commands are very similar in effect but have very different underlying implementations Understanding how they work is crucial if you are to use the best tool for the job Doc All in This File Project Solution These commands work by using Visual Studio s Intellisense database to locate all the relevant code elements in a file and document them This works very well when the Intellisense information is available However as mentioned above depending on the version of Visual Studio the programming language and whether the code has been compiled varying degrees of information will be available and these commands can therefore fail In particular e Some languages offer no intellisense support at all so these commands simply will not work e They will miss out code that lies in disabled if blocks e They will miss out code when the code has not been successfully compiled e In languages other than CH and VB that support intellisense these commands may sometimes report that they found nothing to document This can usually be cured by ensuring intellisense is enabled rebuilding the solution and in some cases rebooting Visual Studio e In C C attempting to read the intellisense needed within header files does not work reliably frequ
122. t or delete them once you have added your own rules This allows your rules to be executed followed by the default rules thus adding your rules without losing any existing auto doc functionality The full set of customisation files that can be added is e UserVariables xml e DocXmlTemplates xml e DoxygenTemplates xml e File xml e Namespace xml e Exceptions xml e Typedefs xml e Enums xml e Variables xml e Classes xml e Interfaces xml e Methods xml e MethodReturns xml 50 e Parameters xml e TypeParameters xml e WordExpansions xml e Replacements xml replacements acronyms e NonSplittable xml unsplittable terms e Prefixes xml A similar set of files can be used to override the settings in prefs xml e DocComment xml e DocXml xml e Doxygen xml e Format xml The file contents should be in exactly the same format as the corresponding section of rules xml or prefs xml For example you can augment the method documentation with a Methods xml containing the following lt xml version 1 0 encoding utf 8 lt Methods gt If name SelfDestruct desc Starts a 5 minute countdown before the computer explodes gt lt Methods gt To remove your customisations simply delete the custom file By using the Rules Path in the Advanced Customisation tab you can place your customisations in any folder s you wish which allows them to be easily checked into your source control system for safekeeping and
123. t this uses amp lt and amp gt so that it will be treated as plain text rather than XML You will also need to set up the useremail user variable appropriately in the UserVariables section to support this example amp lt file amp gt amp lt copyright file leafname extension company company amp gt Copyright c year All Rights Reserved amp lt copyright amp gt amp lt author amp gt user amp lt author amp gt amp lt email amp gt useremail amp lt email amp gt amp lt date amp gt date amp lt date amp gt amp lt summary amp gt fileDescription amp lt summary amp gt amp lt file amp gt 61 XML comment If you include one or more XML elements in the comment Atomineer treats the template as a normal XML template lt file gt lt prototype gt projectpathname lt prototype gt amp 5 lt summary gt lt file gt Further control of file header footer comments can be achieved using the following attributes e separators false By default Atomineer will use your configured Atomineer comment syle separators for the file comment For full control of the text that is inserted this can be disabled so that the text can be treated verbatim e filetypesz h hpp Target a template to specific set of file extensions so you can use a different header style in h and cpp files for example The first template that matches the filetype will be used so this must precede any file templa
124. te that doesn t specify any specific filetypes e _addfooter true in a file hader will instruct Atomineer to automatically add the file footer as well This is handy if you use a paired header footer such as an ifdef endif in a header file Due to the number of options available achieving the exact file header you want can sometimes be a bit tricky so if you would like help just email support with an example of the header text you wish to achieve and we ll be happy to help you design the Templates Conversions Section Atomineer is capable of converting between different comment styles skins and also between DocXml Doxygen Qt and JavaDoc comment formats Note that at this time the primary conversion process that is supported is Doxygen JavaDoc to DocXml simply because there has so far been no demand to convert DocXml the other way However basic conversions are already in place to convert from DocXml if required Please email us if you encounter any mark up that is not converted well and where possible we will try to upgrade Atomineer to support your conversion needs To convert between Doc Comment styles formats you may do any of the following 1 To convert between different block format skins set the Alt Separator Alt LineHeader and Alt SeparatorB preferences in your Prefs xml so that Atomineer knows what the old comment format looks like See the User Manual for details 2 Set your Doxygen or DocXml templates u
125. tes a new Thingummy containing the required number of Wotsits pInfo If non NULL the information NumWotsits The number of wotsits NULL if it fails else IB B II B B Bg gM UL LL P g M HL PL Bg M P P P P P PPP P P Mg UATT A Thingummy MyNamespace MyClass CreateThingummy CreateInfo pInfo int NumWotsits const return NULL Open C C Source or Header deprecated Default hot key sequence Ctrl Shift A Ctrl Shift X When executed in a C C source header file opens the matching header source file Usage Execute the command when you are working in a C C header or source file Description When executed in a C C source header file this simply opens the matching header source file The files must be in the same project and use the same base filename 99 Hide Doc Comments using Outlining deprecated Uses Visual Studio s Outlining feature to hide all Documentation XML Comments in your code Usage Execute the command at any time or have it automatically executed whenever you open a code document by enabling the preference Description This command hides all multi line DocComments lines beginning with in your file using the Outlining feature of the Visual Studio Editor This allows you to see just the code without the comments interfering with your view To see the text of the comments just hover the mouse over the to show a tool tip To edit a comment double click the to re display
126. tes esses enne nnne nnn nnns nnne i nans sss na an 60 Conversions SECTION oe ei c eL t UE AE c PUPA UAR AEG eL Dt UE E uet 62 AutoDoc Section CGomrtnands ie rn evt ee ete n D e e e ee tera 64 AutoDoc Section Using Variables cccccccccccecsssesssaececececesseseeaeceeecesseseaaeseeeesessseaaeaeeseseessesnaaeas 66 AutoDoc Section Documenting specific Code Elements 68 Automated Comment Conversion ceeeeeeee esee ee eee eene eene nnne het nt nhan nanus tenent nhan ss KREE 73 Custom Conversion Rules 2 n Eege DEES scnucvencuaaness e ERE PR LAE RR sh e eR EE aa o e Ede eR REESE EES 74 Pre processing to help Atomineer Parse your Code sess nnn 76 2 Regular Expression Replacements ccccesesssssscecececesseseaeseeeeecesseseaaeseceescesseseeaeeeeeesseeseeaeeeeeeeseesaes 76 Macro Addin Extension Commands cccsessccecceececsesencceccesceessseaececcescecssneaeeecceeceesentaeeeeeeeeeereas 77 Atomineer Menu Commands eeeeeeeeee esee sees KREE eene nsns enun sett nt stas snis n sett nt ns sn snis n steer nnns 80 tele MRT en EE 80 Documentation VIewer x SR oe OR i tm 81 Document All in this Scope aa a aaa a e a LAEE ra e E ae ar E a orara ERATE aaia ieaiai Tet 82 Document All in this File Project Solution 83 Document All in Chosen FileSis senina esee eene nennen tnn nnne nennt entren enne nnns nnn enne 85 Delete Documentation from this File eee ceeeeesee
127. th a comment header or E ee summary Finds a user account EE TT lt summary gt Finds a user account lt summary gt GEET DEENEN Advanced topic Choosing different styles for each coding language Atomineer can use a different comment style for each coding language you use The settings that you edit by default are the global settings they apply to all languages However if you wish you can create a separate set of preferences for each language you use In the title strip for the section you will see a drop down menu icon i es Atomineer Pro Documentation Preferenc Doc E icome Doc Style Doc Formatting Doc S Welco Add Doc Comment System Documentation Xml Comment sy Top eonarator Click this and a menu will be shown Quick Setup He Edit Global Settings c Cand C Visual Basic r C and C Xml ett f A Override these settings fo Java JavaScript TypeScript LI gt ond ci 1 0 d Python xcept after use 7 dnc Cormeen From the menu choose Override these settings for any language you wish to use special settings for and the currently shown settings will be duplicated for the language you have chosen The title strip in the preferences will go blue and indicate the language name you are configuring Also the name of the language will go bold in this drop down menu to i
128. the outlined text Hide Attributes using Outlining deprecated Uses Visual Studio s Outlining feature to hide Attributes in your C code Usage Execute the command at any time or have it automatically executed whenever you open a code document by enabling the preference Description This command hides all C Attributes in your file using the Outlining feature of the Visual Studio Editor This allows you to see just the code without the attributes interfering with your view To see the text of the attributes just hover the mouse over the to show a tool tip To edit the attribute double click the to re display the outlined text 100
129. times as you like within a description The following variables are defined mips Insertion Point The place where the cursor will be left after the comment is inserted Use only one ip in any doc comment Sere For wildcard matches the match command inserts the text that matched the wildcard In cases involving two wildcards the variables 96match 196 and 96match296 are used APA Depending on the context more variables will exist In most cases name will return the full name of the code element being documented and sName will return it in sentence form with spaces between words and abbreviated words expanded to their full name but some contexts will provide much more information For example Methods provide name 96sname 6 retType YnumArgs 96argName 196 96argType196 Variables used to insert text can have additional processing commands applied to that text Each command is of the form command and you can append as many commands as you like e g match Sentence StripLastWord SCase Plural would have the effect of converting the name DivideByZeroException into the text Divide by zeroes 66 The available commands are no suffix Sentence FirstWord LastWord StripFirstWord StripLastword LCase UCase WCase SCase Camel Pascal Plural Leaf StripGen SafeGen Use the text verbatim DivideByZeroException Insert spaces between words retaining exist
130. tion Templates This is a simple proves which is detailed in Documentation Rules and Templates below Using Intellisense The next group of options control how Atomineer uses Visual Studio s Intellisense system This allows Atomineer to search through classes and their base classes for related documentation that it can duplicate a ailable When Vi formation is ntellisense Uu sual Studio U Vi Duplic ate docum entation f ombase classes over des and over oads n de ived classes Generate seealso er tes forbases Suppress ocal doc ymentation rt mires fo ove rides ppress jocal doc umentation Gene ate seea iso e for S id tat In overridden methods properies The first checkbox controls duplication of existing documentation Examples of this are If you have a parameter named userId used throughout a class Atomineer can duplicate the existing documentation every time it is used to save you having to rewrite the description of the userld parameter again and again If you have several overloads of a method ina class Atomineer will duplicate as much documentation as it can between them If you override a virtual method or implement an interface Atomineer will copy the description from the base class interface The options below this can be used to automatically add see also entries to documentation for base classes interfaces for a class and base classes interfaces for methods In addition you can Suppress Lo
131. tomatically generated documentation is built by executing the rules in the lt AutoDoc gt section This is broken into sub sections for all the main documentation entries classes methods parameters returns etc plus an additional lt WordExpansions gt section that defines abbreviations and the text that they should be expanded into The rules for the appropriate entry type are executed as a script There are a few very simple commands If command This command evaluates a set of conditions If any condition is true the command is executed Each condition tests a variable using an XML attribute where the name of the attribute is the variable to test and the attribute value to test is a string to test against The matches are case insensitive and multiple tests on a single variable can be combined by using a comma as a logical or If name vehicleSpeed carSpeed carVelocity Different variables can be tested simultaneously by using several attributes These are combined in a logical and operation i e the following only matches a method called Getlndex that returns an int If name GetIndex retType int A special wildcard can be used to match any sequence of characters It can be used in the following ways text text te xt text If a string with one wildcard is matched then Atomineer sets the variable match to the matched text If two wildcards are used the matches are placed into match1
132. umenting true boolean values e g true TRUE lt c gt true lt c gt The text used for documenting false boolean values The text used for documenting null pointer reference values The text used for documenting nullptr pointer values true false to enable or disable style cop compatible descriptions Note that this is overridden by the value set in the main preferences set to true to document the primary base class only with a lt see cref gt gt set to true to document ALL base classes and or interfaces with lt see cref gt set to true to document overrides where possible with see cref gt Note that you also need to disable duplication of base documentation in the preferences to allow these rules to be applied for overrides set to true to use Attribute meta data when generating documentation set to true to always add in for parameters that are not out or in out This setting is ignored if suppressInOut true set to true to suppress the addition of in out in out to paramter descriptions Note that this overrides alwaysAddInForParams When documenting each type being documented provides a set of useful variables For example for a method the method s name return type and parameter names and types are all supplied to the rules being executed More details of the type specific variables are listed later in this document 53 In addition the following global variabl
133. unanswered questions which significantly influence how we must write our code and possibly whether this method is the one we want to use at all these might include e What is the return value Is it an index into an C style array a value from 0 to numitems 1 o Is it an index into a Visual Basic style list a value from 1 to numltems o Is ita hash value unique ID database table key or other special identifier o Is aspecial return value e g 1 or an error code returned or an exception thrown if the user isn t found e What will happen if username is nu11 Are blank strings valid e Are there any code contracts that this method will enforce e Can names include spaces e Is userName the display name Jonathan R Doe or a login name JohnDoe 13 e Will the method take a long time to execute in which case the results may need to be cached or is it a quick method that can be called whenever needed Does it involve a round trip to the database or is the information held locally e If the database doesn t respond or the user name is not found will an exception be thrown Self documenting code doesn t answer these questions Of course if we had access to the source code we could spend a few minutes or hours finding it and reading through it and the tree of methods it calls to determine the answers we need but it would be much quicker and easier for us if we could instantly access a summary of the information we n
134. undone This can be used in the following ways 82 e Quickly and easily build the documentation structure for all the entries in an enum definition e Convert existing comments e g in the Visual Studio default XmlDoc format into the configured Atomineer format e Quickly update existing documentation after changing the Atomineer block format or preferences e Automate an initial documentation pass After executing this command it is highly recommended that you read through and update the resulting documentation to be sure that it is complete correct and accurate Important Notes e This command is affected by the restrict documentation by access level preference By default all code elements will be documented However in C Visual Basic and Java code this option can be used to restrict the generated documentation so that it only applies to code elements with the correct access level Generally this is used to apply documentation to just the public members of a library or suppress documentation of private members while allowing public protected internal members to be documented Please note that as C PHP Java JavaScript and Typescript access levels are not usually specified within the code element declaration this option is unavailable or only partially available for those languages e This command operates in two modes Initially it will try to use Visual Studio s Intellisense CodeElement database to determine what to
135. ustom lt Conversion gt Rules In addition Rules xml contains a special section Conversions which tells Atomineer how to convert the entries it finds when converting legacy comments This can e Delete unwanted entries e g delete ingroup entirely e Rename entries e g description to lt remarks gt Note that at this time the primary conversion process that is supported is Doxygen JavaDoc Qt to DocXML simply because there has so far been no demand to convert DocXML the other way However basic conversions are already in place to convert from DocXml if required Please email support atomineerutils com if you encounter any mark up that is not converted well and where possible we will try to upgrade Atomineer to support your conversion needs Also the macro extension pre processing approach described below may help you to handle your conversion needs for yourself To convert between Doc Comment styles formats you may do any of the following 1 Toconvert between different block format skins set the Alt Separator Alt LineHeader and Alt SeparatorB preferences in your Prefs xml file so that Atomineer knows what the old comment format looks like 2 Set your Doxygen or DocXML Templates up to indicate the legal entries in your new comment format and how they should be ordered within the new comment block Any entries that have the same tag in both old and new formats e g param param will be automatically conv
136. uted if a rule causes the text to be altered Macro Addin Extension Commands Visual Studio has a built in extensibility model that allows end users to write their own code to automate activities within the IDE Depending on the version of Visual Studio this is done by writing a Macro Add in or Extension usually in Visual Basic or CH Regardless of whether you use a Macro Add in or Extension methods in your code can be exposed to the Visual Studio system including Atomineer Atomineer uses this to allow you to insert custom pre processing as follows e When Add Doc Comment is executed it locates the existing comment to be parsed if any e It selects the text in the comment and then calls your code which can read the selection process the text it contains and write back any replacement text it wishes e Atomineer then reads the new selection and parses it as normal In this way any legacy comment can be converted by writing a simple parser for your old format and applying a rough conversion to make it look like a Doxygen or XmlDoc format This conversion can be very brute force It does not need to provide tidy output just something that conforms enough to the syntax Atomineer expects to allow it to parse the text correctly 77 To enable this processing you will need to first create a macro add in extension command to be executed Example Visual Basic processing code to get you started can be downloaded from here htt
137. y gt Opens the database lt summary gt void OpenDatabase You can independently set the gap between commands and the start of code scopes and the comment so that you don t get unwanted space at the start of regions scopes so you could use 1 line after a region even if you normally require 3 blanks above region Database lt summary gt Opens the database lt summary gt void OpenDatabase 25 Or if you prefer disable this feature by un ticking the check box and Atomineer will leave the blank lines above below the comment exactly as you originally typed them Special Cases for Simple Comment Styles The Simple comment style options are primarily used for member variable and enum value comments e ELLALA style overrides id Doc Comment member variables le line i e for k will fit on a sing tire comment bloc ment style ifthe en Use simple com n d single line comments to the nigh Sg e and starting no earlier than co den For variables an RER Fe and suffi D x Wed v I using the prefix If simple comment style is enabled when the entire documentation comment body could fit onto a single line i e it s a single entry comment with a very brief description it will be output in this form lt summary gt Opens the database lt summary gt Instead of a full comment for example 1 1111111111 11 1 1 1 11 111 1
138. ystem containing thousands of rules generates meaningful documentation for code elements based on common naming practices naming conventions and can even combine information on parameter and return types etc with the naming to deduce more useful documentation If existing documentation is available on an overridden base class method property or an implemented Interface method property it will be copied into your new documentation comment If existing documentation is available on other overloads of a method the docs from the best match overload will be copied If a parameter has been used and documented in other methods of a class the documentation from the best match will be copied All exceptions thrown directly within a method will be documented automatically including ones generated by CH Code Contracts D The three features marked above rely on the Visual Studio Intellisense system If this is disabled your documentation is not in Documentation XML format for use by Intellisense or the Intellisense information is not available e g in C Java PHP or UnrealScript code and sometimes in C CH or VB if the code hasn t compiled successfully or is not included in an open Project then Atomineer will have no choice but to fall back to its regular auto documentation generation algorithm All of the above is configurable The style of blocks the entries they contain and their ordering indentation styles and word wra

Atomineer User Manual - Atomineer Pro Documentation for

Contents

Download Pdf Manuals

Related Search

Related Contents