Search Results

Search found 10963 results on 439 pages for 'documentation generation'.

Page 3/439 | < Previous Page | 1 2 3 4 5 6 7 8 9 10 11 12  | Next Page >

• Where should a programmer explain the extended logic behind the code?

  - by SRKX

  I have developed a few quantitative libraries in C# where it is important to understand not only the classic information that goes with the XMLDoc comments (which contains basic information with the method signature) but also the mathematical formulas being use within the methods. Hence I would like to be able to include extended documentation with the code, which could contain, for example Latex formulas, graphs, and so on. Do you think such information should be included in the API documentation? Or should it be included in a dev blog for examples? Are there common tools that are usually used for this kind of purposes?

  Read the article

• Using Cucumber or RSpec+Selenium to create end user documentation?

  - by carolclarinet

  Has anyone tried creating end user (potentially online, potentially to be printed) help/documentation out of your cucumber scenarios? Or taken screenshots for use in documentation using RSpec and Selenium RC's ability to do so? For Cucumber, I'm imagining something like: Scenario: If you want to add a link Given I am on the edit blog post page When I press the "add link" button And I type in a link URL "http://stackoverflow.com" And I click "OK" Then the blog post should have 1 link Translating to the documentation: If you want to add a link, go to the edit blog post page. Press the "add link" button and type a URL, like "http://stackoverflow.com", into the link URL field. Click "OK". Would it be worth my time to try and, for one, write something to parse my Cucumber features into documentation, and two, to write/structure my Cucumber features in such a way as to create good documentation? Would the resulting documentation end up sounding really boring without much variation in the structure? Is there anything else out there like this idea? Doxygen looks like it's more for code documentation than end-user documentation. What about automatically taking screenshots? This seems like a more fruitful path-- just reuse the code that takes a screenshot when an RSpec test fails and have it take one in prescribed situations. Is there a better way to do this?

  Read the article

• Are XML Comments Necessary Documentation?

  - by Bob Horn

  I used to be a fan of requiring XML comments for documentation. I've since changed my mind for two main reasons: Like good code, methods should be self-explanatory. In practice, most XML comments are useless noise that provide no additional value. Many times we simply use GhostDoc to generate generic comments, and this is what I mean by useless noise: /// <summary> /// Gets or sets the unit of measure. /// </summary> /// <value> /// The unit of measure. /// </value> public string UnitOfMeasure { get; set; } To me, that's obvious. Having said that, if there were special instructions to include, then we should absolutely use XML comments. I like this excerpt from this article: Sometimes, you will need to write comments. But, it should be the exception not the rule. Comments should only be used when they are expressing something that cannot be expressed in code. If you want to write elegant code, strive to eliminate comments and instead write self-documenting code. Am I wrong to think we should only be using XML comments when the code isn't enough to explain itself on its own? I believe this is a good example where XML comments make pretty code look ugly. It takes a class like this... public class RawMaterialLabel : EntityBase { public long Id { get; set; } public string ManufacturerId { get; set; } public string PartNumber { get; set; } public string Quantity { get; set; } public string UnitOfMeasure { get; set; } public string LotNumber { get; set; } public string SublotNumber { get; set; } public int LabelSerialNumber { get; set; } public string PurchaseOrderNumber { get; set; } public string PurchaseOrderLineNumber { get; set; } public DateTime ManufacturingDate { get; set; } public string LastModifiedUser { get; set; } public DateTime LastModifiedTime { get; set; } public Binary VersionNumber { get; set; } public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; } } ... And turns it into this: /// <summary> /// Container for properties of a raw material label /// </summary> public class RawMaterialLabel : EntityBase { /// <summary> /// Gets or sets the id. /// </summary> /// <value> /// The id. /// </value> public long Id { get; set; } /// <summary> /// Gets or sets the manufacturer id. /// </summary> /// <value> /// The manufacturer id. /// </value> public string ManufacturerId { get; set; } /// <summary> /// Gets or sets the part number. /// </summary> /// <value> /// The part number. /// </value> public string PartNumber { get; set; } /// <summary> /// Gets or sets the quantity. /// </summary> /// <value> /// The quantity. /// </value> public string Quantity { get; set; } /// <summary> /// Gets or sets the unit of measure. /// </summary> /// <value> /// The unit of measure. /// </value> public string UnitOfMeasure { get; set; } /// <summary> /// Gets or sets the lot number. /// </summary> /// <value> /// The lot number. /// </value> public string LotNumber { get; set; } /// <summary> /// Gets or sets the sublot number. /// </summary> /// <value> /// The sublot number. /// </value> public string SublotNumber { get; set; } /// <summary> /// Gets or sets the label serial number. /// </summary> /// <value> /// The label serial number. /// </value> public int LabelSerialNumber { get; set; } /// <summary> /// Gets or sets the purchase order number. /// </summary> /// <value> /// The purchase order number. /// </value> public string PurchaseOrderNumber { get; set; } /// <summary> /// Gets or sets the purchase order line number. /// </summary> /// <value> /// The purchase order line number. /// </value> public string PurchaseOrderLineNumber { get; set; } /// <summary> /// Gets or sets the manufacturing date. /// </summary> /// <value> /// The manufacturing date. /// </value> public DateTime ManufacturingDate { get; set; } /// <summary> /// Gets or sets the last modified user. /// </summary> /// <value> /// The last modified user. /// </value> public string LastModifiedUser { get; set; } /// <summary> /// Gets or sets the last modified time. /// </summary> /// <value> /// The last modified time. /// </value> public DateTime LastModifiedTime { get; set; } /// <summary> /// Gets or sets the version number. /// </summary> /// <value> /// The version number. /// </value> public Binary VersionNumber { get; set; } /// <summary> /// Gets the lot equipment scans. /// </summary> /// <value> /// The lot equipment scans. /// </value> public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; } }

  Read the article

• Procedural object generation and unique identification

  - by 2080

  My question relates to procedural content generation and data management of the emerging objects in a database. I assume a networked game, with a server-client model. Unspecified objects in the game world are generated while the game is running with procedural algorithms (for example perlin noise). The players (/clients) can modify the properties of these objects, but have to notify the server of these changes. How could this communication address unique objects, so that both the server and the client know of which object they are speaking? Not only the inner properties of the objects can differ, but also visible, such as the position. When the player wants to select one of these objects the game has to find out the id - does anyone know which methods or algorithms can accomplish that?

  Read the article

• How to create reproducible probability in map generation?

  - by nickbadal

  So for my game, I'm using perlin noise to generate regions of my map (water/land, forest/grass) but I'd also like to create some probability based generation too. For instance: if(nextInt(10) > 2 && tile.adjacentTo(Type.WATER)) tile.setType(Type.SAND); This works fine, and is even reproduceable (based on a common seed) if the nextInt() calls are always in the same order. The issue is that in my game, the world is generated on demand, based on the player's location. This means, that if I explore the map differently, and the chunks of the map are generated in a different order, the randomness is no longer consistent. How can I get this sort of randomness to be consistent, independent of call order? Thanks in advance :)

  Read the article

• Code Generation and IDE vs writing per Hand

  - by sytycs

  I have been programming for about a year now. Pretty soon I realized that I need a great Tool for writing code and learned Vim. I was happy with C and Ruby and never liked the idea of an IDE. Which was encouraged by a lot of reading about programming.[1] However I started with (my first) Java Project. In a CS Course we were using Visual Paradigm and encouraged to let the program generate our code from a class diagram. I did not like that Idea because: Our class diagram was buggy. Students more experienced in Java said they would write the code per hand. I had never written any Java before and would not understand a lot of the generated code. So I took a different approach and wrote all methods per Hand (getter and Setter included). My Team-members have written their parts (partly generated by VP) in an IDE and I was "forced" to use it too. I realized they had generated equal amounts of code in a shorter amount of time and did not spend a lot of time setting their CLASSPATH and writing scripts for compiling that son of a b***. Additionally we had to implement a GUI and I dont see how we could have done that in a sane matter in Vim. So here is my Problem: I fell in love with Vim and the Unix way. But it looks like for getting this job done (on time) the IDE/Code generation approach is superior. Do you have equal experiences? Is Java by the nature of the language just more suitable for an IDE/Code generated approach? Or am I lacking the knowledge to produce equal amounts of code "per Hand"? [1] http://heather.cs.ucdavis.edu/~matloff/eclipse.html

  Read the article

• What schema documentation tools exist for PostgreSQL

  - by Brad Koch

  MySQL has MySQL Workbench for designing and documenting your schema, and generates CREATE and ALTER scripts based on your design. We're looking at migrating to PostgreSQL in the near future, and we do need a practical way of documenting and modifying the schema structure. What similar tools exist for Postgres (that are OS X/Linux compatible)? Alternatively, what equivalent conventions would be followed for designing and documenting the structure of your Postgres database?

  Read the article

• Does searching documentation and samples look bad?

  - by Mick Aranha

  I am starting a new job in a company with many developers and media people, the layout of the place is open with computers around a skinny oval, I have worked in small teams and programming embedded C, the jobis for objective C I'm still in a medium stage, so I know what I don't know (haha), that means I have to google it and then implement it, So the question is how bad does it look if the guy next to you does lot of searching for coding I mean, at the end of the day I will get the job done, but want to look professional too!

  Read the article

• Speeding up procedural texture generation

  - by FalconNL

  Recently I've begun working on a game that takes place in a procedurally generated solar system. After a bit of a learning curve (having neither worked with Scala, OpenGL 2 ES or Libgdx before), I have a basic tech demo going where you spin around a single procedurally textured planet: The problem I'm running into is the performance of the texture generation. A quick overview of what I'm doing: a planet is a cube that has been deformed to a sphere. To each side, a n x n (e.g. 256 x 256) texture is applied, which are bundled in one 8n x n texture that is sent to the fragment shader. The last two spaces are not used, they're only there to make sure the width is a power of 2. The texture is currently generated on the CPU, using the updated 2012 version of the simplex noise algorithm linked to in the paper 'Simplex noise demystified'. The scene I'm using to test the algorithm contains two spheres: the planet and the background. Both use a greyscale texture consisting of six octaves of 3D simplex noise, so for example if we choose 128x128 as the texture size there are 128 x 128 x 6 x 2 x 6 = about 1.2 million calls to the noise function. The closest you will get to the planet is about what's shown in the screenshot and since the game's target resolution is 1280x720 that means I'd prefer to use 512x512 textures. Combine that with the fact the actual textures will of course be more complicated than basic noise (There will be a day and night texture, blended in the fragment shader based on sunlight, and a specular mask. I need noise for continents, terrain color variation, clouds, city lights, etc.) and we're looking at something like 512 x 512 x 6 x 3 x 15 = 70 million noise calls for the planet alone. In the final game, there will be activities when traveling between planets, so a wait of 5 or 10 seconds, possibly 20, would be acceptable since I can calculate the texture in the background while traveling, though obviously the faster the better. Getting back to our test scene, performance on my PC isn't too terrible, though still too slow considering the final result is going to be about 60 times worse: 128x128 : 0.1s 256x256 : 0.4s 512x512 : 1.7s This is after I moved all performance-critical code to Java, since trying to do so in Scala was a lot worse. Running this on my phone (a Samsung Galaxy S3), however, produces a more problematic result: 128x128 : 2s 256x256 : 7s 512x512 : 29s Already far too long, and that's not even factoring in the fact that it'll be minutes instead of seconds in the final version. Clearly something needs to be done. Personally, I see a few potential avenues, though I'm not particularly keen on any of them yet: Don't precalculate the textures, but let the fragment shader calculate everything. Probably not feasible, because at one point I had the background as a fullscreen quad with a pixel shader and I got about 1 fps on my phone. Use the GPU to render the texture once, store it and use the stored texture from then on. Upside: might be faster than doing it on the CPU since the GPU is supposed to be faster at floating point calculations. Downside: effects that cannot (easily) be expressed as functions of simplex noise (e.g. gas planet vortices, moon craters, etc.) are a lot more difficult to code in GLSL than in Scala/Java. Calculate a large amount of noise textures and ship them with the application. I'd like to avoid this if at all possible. Lower the resolution. Buys me a 4x performance gain, which isn't really enough plus I lose a lot of quality. Find a faster noise algorithm. If anyone has one I'm all ears, but simplex is already supposed to be faster than perlin. Adopt a pixel art style, allowing for lower resolution textures and fewer noise octaves. While I originally envisioned the game in this style, I've come to prefer the realistic approach. I'm doing something wrong and the performance should already be one or two orders of magnitude better. If this is the case, please let me know. If anyone has any suggestions, tips, workarounds, or other comments regarding this problem I'd love to hear them.

  Read the article

• Generate HTML pages from some template

  - by Appu

  I have an open-source project for which I have to generate HTML pages to put on the web. I wanted to keep everything as simple HTML pages. The problem with this approach is if I need to change the design, I have to goto all the pages and change it. This will be tough as I have lot of pages. Is there some kind of HTML generators which can process simple annotated text files? This way, I can maintain the documentation and website contents as plain text files and run it through this program to generate static HTML pages. This also helps in keeping the design consistent. Any help would be great!

  Read the article

• How to document experimental or incomplete APIs like @deprecated?

  - by Michael Levy

  Is there a good term that is similar but different than "deprecate" to mean that a method or API is in the code base but should not be used because its implementation is not complete or will likely change? (Yeah, I know, those methods shouldn't be public, yada yada yada. I didn't create my situation, I'm just trying to make the best of it.) What do people suggest? Experimental, Incomplete, something else? If I'm building javadoc documentation for this API that is still in flux, should I use the @deprecated tag or is there a better convention? To me @deprecated implies that this API is old and a newer preferred mechanism is available. In my situation, there is no alternative, but some of the methods in the API are not finished and so should not be used. At this point I cannot make them private, but I'd like to put clear warnings in the docs.

  Read the article

• Heightmap generation

  - by Ziaix

  I want to implement something like this to create a heightmap: 'Place a group of coordinates evenly across a map, and give them height values within a certain range. Repeatedly create coordinates between all of those coordinates, setting their height by deriving a value that was a mean value of all the surrounding coordinates.' However, I'm not sure how I would go about it - I'm not sure how I could code the part where I place the coordinates in between the existing coordinates. Can anyone give any help/advice?

  Read the article

• Procedural Generation of tile-based 2d World

  - by Matthias

  I am writing a 2d game that uses tile-based top-down graphics to build the world (i.e. the ground plane). Manually made this works fine. Now I want to generate the ground plane procedurally at run time. In other words: I want to place the tiles (their textures) randomised on the fly. Of course I cannot create an endless ground plane, so I need to restrict how far from the player character (on which the camera focuses on) I procedurally generate the ground floor. My approach would be like this: I have a 2d grid that stores all tiles of the floor at their correct x/y coordinates within the game world. When the players moves the character, therefore also the camera, I constantly check whether there are empty locations in my x/y map within a max. distance from the character, i.e. cells in my virtual grid that have no tile set. In such a case I place a new tile there. Therefore the player would always see the ground plane without gaps or empty spots. I guess that would work, but I am not sure whether that would be the best approach. Is there a better alternative, maybe even a best-practice for my case?

  Read the article

• Diamond-square terrain generation problem

  - by kafka

  I've implemented a diamond-square algorithm according to this article: http://www.lighthouse3d.com/opengl/terrain/index.php?mpd2 The problem is that I get these steep cliffs all over the map. It happens on the edges, when the terrain is recursively subdivided: Here is the source: void DiamondSquare(unsigned x1,unsigned y1,unsigned x2,unsigned y2,float range) { int c1 = (int)x2 - (int)x1; int c2 = (int)y2 - (int)y1; unsigned hx = (x2 - x1)/2; unsigned hy = (y2 - y1)/2; if((c1 <= 1) || (c2 <= 1)) return; // Diamond stage float a = m_heightmap[x1][y1]; float b = m_heightmap[x2][y1]; float c = m_heightmap[x1][y2]; float d = m_heightmap[x2][y2]; float e = (a+b+c+d) / 4 + GetRnd() * range; m_heightmap[x1 + hx][y1 + hy] = e; // Square stage float f = (a + c + e + e) / 4 + GetRnd() * range; m_heightmap[x1][y1+hy] = f; float g = (a + b + e + e) / 4 + GetRnd() * range; m_heightmap[x1+hx][y1] = g; float h = (b + d + e + e) / 4 + GetRnd() * range; m_heightmap[x2][y1+hy] = h; float i = (c + d + e + e) / 4 + GetRnd() * range; m_heightmap[x1+hx][y2] = i; DiamondSquare(x1, y1, x1+hx, y1+hy, range / 2.0); // Upper left DiamondSquare(x1+hx, y1, x2, y1+hy, range / 2.0); // Upper right DiamondSquare(x1, y1+hy, x1+hx, y2, range / 2.0); // Lower left DiamondSquare(x1+hx, y1+hy, x2, y2, range / 2.0); // Lower right } Parameters: (x1,y1),(x2,y2) - coordinates that define a region on a heightmap (default (0,0)(128,128)). range - basically max. height. (default 32) Help would be greatly appreciated.

  Read the article

• Random World Generation

  - by Alex Larsen

  I'm making a game like minecraft (although a different idea) but I need a random world generator for a 1024 block wide and 256 block tall map. Basically so far I have a multidimensional array for each layer of blocks (a total of 262,114 blocks). This is the code I have now: Block[,] BlocksInMap = new Block[1024, 256]; public bool IsWorldGenerated = false; Random r = new Random(); private void RunThread() { for (int BH = 0; BH <= 256; BH++) { for (int BW = 0; BW <= 1024; BW++) { Block b = new Block(); if (BH >= 192) { } BlocksInMap[BW, BH] = b; } } IsWorldGenerated = true; } public void GenWorld() { new Thread(new ThreadStart(RunThread)).Start(); } I want to make tunnels and water but the way blocks are set is like this: Block MyBlock = new Block(); MyBlock.BlockType = Block.BlockTypes.Air; How would I manage to connect blocks so the land is not a bunch of floating dirt and stone?

  Read the article

• Procedual level generation for a platformer game (tilebased) using player physics

  - by Notbad

  I have been searching for information about how to build a 2d world generator (tilebased) for a platformer game I am developing. The levels should look like dungeons with a ceiling and a floor and they will have a high probability of being just made of horizontal rooms but sometimes they can have exits to a top/down room. Here is an example of what I would like to achieve. I'm refering only to the caves part. I know level design won't be that great when generated but I think it is possible to have something good enough for people to enjoy the procedural maps (Note: Supermetrod Spoiler!): http://www.snesmaps.com/maps/SuperMetroid/SuperMetroidMapNorfair.html Well, after spending some time thinking about this I have some ideas to create the maps that I would like to share with you: 1) I have read about celular automatas and I would like to use them to carve the rooms but instead of carving just a tile at once I would like to carve full columns of tiles. Of course this carving system will have some restrictions like how many tiles must be left for the roof and the ceiling, etc... This way I could get much cleaner rooms than using the ussual automata. 2) I want some branching into the rooms. It will have little probability to happen but I definitely want it. Thinking about carving I came to the conclusion that I could be using some sort of path creation algorithm that the carving system would follow to create a path in the rooms. This could be more noticiable if we make the carving system to carve columns with the height of a corridor or with the height of a wide room (this will be added to the system as a param). This way at some point I could spawn a new automa beside the main one to create braches. This new automata should play side by side with the first one to create dead ends, islands (both paths created by the automatas meet at some point or lead to the same room. It would be too long to explain here all the tests I have done, etc... just will try to summarize the problems to see if anyone could bring some light to solve them (I don't mind sharing my successes but I think they aren't too relevant): 1) Zone reachability: How can I make sure that the player will be able to reach all zones I created (mainly when branches happen or vertical rooms are created). When branches are created I have to make sure that there will be a way to get onto the new created branch. I mean a bifurcation that the player could follow. Player will follow the main path or jump to a platform to get onto the other way). On the other hand if an island is created by the meeting of both branches I need to make sure the player will be able to get onto the island too. 2) When a branch is created and corridors are generated for each branch how can I make then both merge or repel to create an island or just make them separated corridors. 3) When I create a branch and an island is created becasue both corridors merge at somepoint or they lead to the same room, is there any way to detect this and randomize where to create the needed platforms to get onto the created isle? This platforms could be created at the start of the island or at the end. I guess part of the problem could be solved using some sort of graph following the created paths but I'm a bit lost in this sea of precedural content creation :). On the other hand I don't expect a solution to the problem but some information to get me moving forward again. Thanks in advance.

  Read the article

• I'm tasked with leading the documentation effort for an existing, entirely undocumented, software product - what resources are there to help me?

  - by Ben Rose

  I'm a software developer at a technology company. I have been tasked with leading the documentation effort for the product I work on. The goal is to produce documentation internal to developer, and the project spills over into the business side, where it covers requirements documentation. This project is challenging. Specifically, I'm dealing with a product which: - has been around for a long time, at least 6 years. - has no form of documentation other than some small, outdated pieces here and there. - has comments in the code, but they are technical and do not convey any over-arching behavior (even on technical side). - as a consequence of having little to no documentation, is often unnecessarily complex under the covers In addition, we have not been given a lot of time to work on this project. I do not have any formal documentation or writing background, training, or experience. I have displayed some ability in writing/communication around the office, which may be why I was assigned to this project. Please share your advice or recommendation for resources to help me prepare and deal with this project. I'm looking for references to books/website/forums/whatever, to help me come up with the design of a plan with milestones, learn about best practices, task delegation, templates, buy-in, etc. I'm hoping specifically for resources targeting or giving special mention of introducing good documentation to existing, undocumented, projects. I would be very grateful for your responses. Ben

  Read the article

• Are there good resources for leading documentation for an existing software product having none?

  - by Ben Rose

  Hello. I'm a software developer at a technology company. I have been tasked with leading the documentation effort for the product I work on, both internal to developers as well as spilling over into facilitating the business side of requirements documentation. This internal product has been around for at least 6 years. One challenge is that this software application has no form of documentation other than some small, outdated pieces here and there. There are comments in the code, but they are technical and do not convey any over-arching behavior (even on technical side). As a consequence of having little to no documentation, this product is often unnecessarily complex under the covers adding to the challenge. We are very limited on time that will be given to us to work on documentation. Another thing about me is that I've displayed some ability in writing/communication around the office, but I'm not coming from any sort of documentation or formal writing background (beyond my academic career). Please share your advise or recommend resources, book/website/forum/whatever, for helping me come up with a plan with milestones, best practices, task delegation, templates, buy-in, etc. I'm hoping for a resource targeting or giving special mention of introducing good documentation on existing projects where there previously was none. I would be very grateful for your responses. Ben

  Read the article

• printable PHP manual - 'all but the Function Reference section'

  - by JW01

  My Motivation I find it easier to learn things by reading 'offline'. I'd like to lean back and read the narrative part of a paper version of the official php manual. My Scuppered Plan My plan was to download the manual, print all but the Function Reference section and then read it. I have downloaded the "Single HTML file" version of the manual from the php.net download page. (That version did not contain any images, so I patched-in the ones from the Many HTML files version with no problem.) My plan was to open that "Single HTML file" in an HTML editor, delete the Function Reference section then print it out. Unfortunately, although I have tried three different editors, I have not been able to successfully load-up that massive html file to be able to edit it. Its about (~40MB). I started to look into the phpdoc framework with a view to rendering my own html docs from the source...but that's a steep learning curve for a newby..and is a last resort. I would use a file splitter, but they tend to split files crudely with no regard for html/xml/xhtml sematics. So the question is... Does anyone know know where you can download the php manual in a version that is a kind of half-way house between the 'Single HTML file' and the 'Many HTML files'? Ideally with the docs split into 3 parts: File 1 - stuff before the function reference File 2 - function reference File 3 - stuff after the function reference Or Can you suggest any editors/tools will enable me to split up this file myself?

  Read the article

• Is BDD actually writable by non-programmers?

  - by MattiSG

  Behavior-Driven Development with its emblematic “Given-When-Then” scenarios syntax has lately been quite hyped for its possible uses as a boundary object for software functionality assessment. I definitely agree that Gherkin, or whichever feature definition script you prefer, is a business-readable DSL, and already provides value as such. However, I disagree that it is writable by non-programmers (as does Martin Fowler). Does anyone have accounts of scenarios being written by non-programmers, then instrumented by developers? If there is indeed a consensus on the lack of writability, then would you see a problem with a tool that, instead of starting with the scenarios and instrumenting them, would generate business-readable scenarios from the actual tests?

  Read the article

• How to write comments to explain the "why" behind the callback function when the function and parameter names are insufficient for that?

  - by snowmantw

  How should I approach writing comments for callback functions? I want to explain the "why" behind the function when the function and parameter names are insufficient to explain what's going on. I have always wonder why comments like this can be so ordinary in documents of libraries in dynamic languages: /** * cb: callback // where's the arguments & effects? */ func foo( cb ) Maybe the common attitude is "you can look into source code on your own after all" which pushes people into leaving minimalist comments like this. But it seems like there should be a better way to comment callback functions. I've tried to comment callbacks in Haskell way: /** * cb: Int -> Char */ func foo(cb) And to be fair, it's usually neat enough. But it gets into trouble when I need to pass some complex structure. The problem being partly due to the lack of type system: /** * cb: Int -> { err: String -> (), success: () -> Char } // too long... */ func foo(cb) Or I have tried this too: /** * cb: Int -> { err: String -> (), * success: () -> Char } // better ? */ func bar(cb) The problem is that you may put the structure in somewhere else, but you must give it a name to reference it. But then when you name a structure you're about to use immediately looks so redundant: // Somewhere else... // ResultCallback: { err: String -> (), success: () -> Char } /** * cb: Int -> ResultCallback // better ?? */ func foo(cb) And it bothers me if I follow the Java-doc like commenting style since it still seems incomplete. The comments don't tell you anything that you couldn't immediately see from looking at the function. /** * @param cb {Function} yeah, it's a function, but you told me nothing about it... * @param err {Function} where should I put this callback's argument ?? * Not to mention the err's own arguments... */ func foo(cb) These examples are JavaScript like with generic functions and parameter names, but I've encountered similar problems in other dynamic languages which allow complex callbacks.

  Read the article

• How to create programming flowchart/documentation from VB.NET source code?

  - by Greg

  Hi, what tools do you use to create programming flowchart/documentation from VB.NET source code? There are absolutely no comments/documentation at present. I am a beginner, i.e. I tried Sandcastle but it is way over my head and could not get it going, not even with GUI. Fatesoft's CodeVisual To Flowchart is OK but it is almost the same as the code and I still don't understand the code.

  Read the article

• What tools are available to generate end user documentation?

  - by Rowland Shaw

  End user documentation on how to use applications is an important part of the user experience of applications, irrespective of whether they are winforms, wpf or even asp applications. In a startup or internal development team situation, where there isn't a dedicated documentation department, it can take a lot of resources to maintain screen shots and associated user documentation, such as on-line help or even printable manuals. What tools are available to assist in creating screenshots of all the "screens" within an application (be they winforms, wpf or aspx) to help automate the capture of screen shots, and associating with the relevant documentation? In addiiton, are there any that allow automation of annotations of a particular control (so use cases like: Draw a red box around the Username control with a callout to say "This is where you'd enter your user name, in the form '[email protected]'")?

  Read the article

• Text template or tool for documentation of computer configurations

  - by mjustin

  I regularly write and update technical documentation which will be used to set up a new virtual machine, or to have a lookup for system dependencies in networks with around 20-50 (server-side) computers. At the moment I use OpenOffice Writer with text tables, and create one document per intranet domain. To improve this documentation, I would like to collect some examples to identify areas where my documents can be improved, regarding general structure and content, to make it easy to read and use not only for me but also for technical staff, helpdesk etc. Are there simple text templates (for example for OpenOffice Writer) or tools (maybe database-driven) for structured documentation of a computer configuration? Such a template / tool should provide required and optional configuration sections, like 'operating system', 'installed services', 'mapped network drives', 'scheduled tasks', 'remote servers', 'logon user account', 'firewall settings', 'hard disk size' ... It is not so much low-level hardware docs but more infrastructure / integration information in these documents (no BIOS settings, MAC addresses).

  Read the article

• What program do you use to write technical documentation?

  - by Tatu Ulmanen

  I'm writing an architecture/technical documentation for an inhouse project and I'm becoming more and more frustrated with Microsoft Word as I seem to use most of my time getting things to align correctly. Word has horrible usability issues but I didn't come here to rant, rather I'd like to know whether there exists something more suitable for the job. The point of this documentation is to provide a "big picture" of the system, and as such I'm not generating documentation from source code but rather writing it all by hand. Are there any alternatives to Microsoft Word for writing properly formatted technical documentation with less frustration?

  Read the article

< Previous Page | 1 2 3 4 5 6 7 8 9 10 11 12  | Next Page >